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Emacs (pronounced "ee-max") started off in 1 976 as a series 
of "editor macros" (hence its name) written by Richard Mat- 
thew Stallman for the TECO text editor on the DEC PDP-10 
minicomputer. Since becoming its own program separate from 
TECO, it has become extremely popular and widely used for 
two main reasons: first, free versions of Emacs are available for 
nearly every computer in existence; second, it's completely 
customizable. 
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Many text editors and word processors claim to be "com- 
pletely customizable." Some let you reassign each key's pur- 
pose, and they let you assign a series of operations to be 
performed by one or two keystrokes or menu choices. Perhaps 
this series of operations can have loops of repeated statements 
and "if" statements that execute one or another group of 
instructions based on whether a particular condition is true, if 
so, the editor's proponents claim that its macro facility features 
a "full-fledged programming language." This is usually an 
exaggeration, but not with Emacs. 

Emacs's accompanying programming language is known as 
"Emacs LISP" because it's based on LISP, a grand old program- 
ming language that first gained fame for its use in artificial 
intelligence work. (The connection between a text editor and 
artificial intelligence? Manipulating text.) You don't need to 
learn Emacs LISP to benefit from it; many Emacs users have 
made their Emacs LISP programs available to anyone who 
wants to run them, whether these other users understand the 
syntax used to create them or not. 

One collection of Emacs LISP programs called PSGML can 
read and parse a DTD and document instance well enough to 
turn Emacs into a menu-driven SGML editor. PSGML can: 

• Insert required elements automatically. 

• Help you find tagging mistakes. 

• Display tags, data content, comments, and entity refer- 
ences in different fonts or colors, making data content eas- 
ier to read and markup easier to find. 

• Let you enter and edit element attributes using a form with 
helpful information about declared and default values. 

• Enable access to all its important functions (and, when 
inserting tags, lists of valid element types) on pull-down 
menus when run on systems that support them. 

And, thanks to its author Lennart Staflin, PSGML is as free as 
Emacs! 
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Editing SGML Documents with the Emacs Text Editor 

In this chapter, we'll first learn the basics of using Emacs with 
any text file. Then, we'll learn how to install PSGML and use it 
to edit SGML documents. 



<TIP> Emacs's venerable age means that various terms may seem 
odd to users accustomed to the terminology of current big- 
selling software. This chapter explains the Emacs terms and 
the equivalent terms on currently popular word processors 
and editors when possible so that you'll more easily under- 
stand the vocabulary used in Emacs's on-line help and other 
available literature. 



Getting Emacs 

Emacs's age and the free availability of its source code have 
led to different versions being available. The standard-bearer at 
any given time is the Free Software Foundation's GNU Emacs; 
the further an Emacs implementation deviates from the GNU 
version, the greater the chance that PSGML won't work with it. 
I used the DOS EMX release 19.29.2 version of GNU Emacs 
and the 19.30 Windows 95 version of GNU Emacs while test- 
ing this chapter, and I used version 1 .0 alpha 6 of PSGML. 

All versions of PSGML work with release 19.19 or later of 
GNU Emacs and release 19.9 or later of the XWindows off- 
shoot of GNU known as Xemacs (formerly Lucid Emacs). As 1 
write this, the most recent version of GNU Emacs is 1 9.34. 



<TIP> Staflin developed PSGML on a UNIX system, so if you have 
problems running the latest version under your operating sys- 
tem, try another release of PSGML. He makes several releases 
available. 
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Editing Text Files with Emacs 

Emacs often gives you a choice of several keystrokes and 
commands to perform certain operations. This section covers 
the minimum amount necessary to get by. Keep in mind that 
many procedures described here have alternatives that you 
may prefer. 

Starting and Quitting Emacs 

To start up Emacs, simply enter 



emacs 



at your operating system prompt. In a windowed environment, 
you can set an icon to perform a similar command. 

When Emacs is started with no filename as a parameter, it 
often displays information about your version of Emacs (see 
Fig. 2.1). 



Buffers Files Tools Edit Search Help 
GNU Emacs 19.3B.1 (i386-»-winJi. B) of Thu Feb 01 1996 on WBUE 
Copyr-ight (C) 1995 Free Software Foundation, Inc. 

Type C-h for help; C-x u to undo changes. ("C-' means use CTRL key.) 
To kill the Emacs job, type C-x C-c. 
Type C-h t for a tutorial on using Enacs. 

Type C-h i to enter Info, uhich you can use to read GNU documentation. 
C-mouse-3 (third mouse button, uith Control) gets a mode-specific menu. 
If an Emacs session crashed recently, 

type M-x recouer-session RET to recover the files you were editing. 

GNU Enacs cones with fiBSOLUTELV NO WflRRflNTV; type C-h C-w for full details. 
Vou nay give out copies of Enacs; type C-h C-c to see the conditions. 
Type C-h C-d for infornation on getting the latest version .| 



I 




Figure 2.1. Opening Emacs screen in a windowed environment 
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Editing SGML Documents with the Emacs Text Editor 

The bottom line, which begins "For information about..." in 
the illustration, is known as the "minibuffer." You and Emacs 
enter information there to provide details about what each of 
you is doing (or trying to do). Emacs puts messages there to tell 
you things like the number of replacements a search-and- 
replace operation performed; you use the minibuffer as a com- 
mand line when necessary and enter text in response to any 
questions Emacs asks you — for example, whether to save an 
edited file when quitting. 

Just above the minibuffer is the mode line, which tells you 
the name of the buffer or file you're editing and other details 
about it. It tells you, as a percentage of the file's total number of 
lines, how far down in the file the displayed part is. For exam- 
ple, if your cursor is two-thirds of the way down, it says "66%." 

The mode line also tells you, in parentheses, which major 
mode the current buffer is in. Emacs major modes are states in 
which certain commands are available and certain settings 
have particular values. Minor modes generally describe a spe- 
cific setting; for example, overwrite mode is a minor mode. 

Customized major modes are available to edit the text of var- 
ious programming languages and other kinds of text. In fact, 
this chapter covers one of these major modes: the PSGML 
mode. 

When starting up Emacs, adding a filename to the emacs 
command, like this, 

emacs myfile.txt 

tells Emacs to edit that file, whether it exists or not. If it doesn't 
exist, Emacs creates an empty buffer with that file's name and, 
the first time you tell Emacs to save the file, it creates that file 
for you. 

But what's a buffer? It's an area in the computer's memory 
set aside for each document. Nearly all text editors, word pro- 
cessors, and even spreadsheet programs set aside an area in 
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memory to work on a copy of each document that you edit. 
This is why you lose your work if the computer loses power or 
a program stops running before you save changes — you're 
making changes to a copy of your document in the computer's 
memory. 

Although many programs use the concept of buffers, Emacs 
uses the word more than most, so familiarity with the term 
makes it easier to understand Emacs's on-line help and error 
messages. Emacs buffers with files in them are usually named 
after those files. 

To end an Emacs session enter c-x c-c (ctri+x followed 
by ctrl+c — the next section further describes Emacs's nota- 
tion for expressing combination keystrokes). If your version of 
Emacs has menus, select Exit Emacs from the Files menu. If you 
have no unsaved changes, Emacs returns you to your operating 
system prompt or closes Emacs's window if you're using a win- 
dowed operating system. If you have buffers with unsaved 
changes, Emacs asks you the following for each one, filling in 
the appropriate path and filenames: 

Save file c: /pathname/filename. ext? (y, n, !, ., q, C-r or C-h) 

It's asking "do you really want to leave Emacs, even though 
you have copies of documents in memory with changes you 
haven't saved onto the disk?" If you made changes that you 
don't want to save, enter n to indicate "no." Enter y to indicate 
"yes," and c-h to invoke the on-line help, which describes the 
other possible answers to this prompt. 

If you answer n to any "Save file?" query, Emacs gives you 
one more chance to recant before finally quitting: 

Modified buffers exist; exit anyway? (yes or no) 
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Editing SGML Documents with the Emacs Text Editor 
Emacs Commands 

Some versions of Emacs offer pull-down menus that let you 
take advantage of most of its features, and PSGML adds several 
new menus to Emacs's regular ones. When entering text and 
moving your cursor around, menus are often slower than key- 
stroke commands, but they're handy for little-used features 
whose keystrokes are difficult to remember. This chapter men- 
tions each command's corresponding menu choice when there 
is one. 

Usually, you tell Emacs what to do with a special keystroke. 
For example, C-a (pronounced "Control A" — shorthand for 
pressing your Ctrl key and the letter "A" together) means 
"jump the cursor to the beginning of the current line." 

You execute many Emacs commands with a key known as 
the "meta" key. Some early computers had a special key with 
this label on it; it was used in combination with other keys just 
as the Ctrl key is. With keyboards that have no "Meta" key 
(which includes every keyboard I've ever seen) you use the 
Escape or Alt keys. 

A metakey combination is often written with an "M-" pre- 
ceding the other key. For example, M-f refers to pressing the 
Escape followed by the f. Note that, unlike the Ctrl key in 
the c-f key combination, you press the f after pressing 
Escape, not while pressing it. If your computer and version of 
Emacs let you use the Alt key for metakeys, press it with the 
other key just as you would press the Ctrl or shift key simul- 
taneously with another key. 

Odd commands actually exist for which you press Escape 
followed by a Ctrl key combination. Instead of writing this as 
M-c-x for meta-control-x, Emacs documentation mercifully 
refers to such a combination as esc c-x. (If your version of 
Emacs lets you use Alt as the metakey, you can press 
Ait+ctri+x.) This chapter only describes one such keystroke. 
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Many Emacs commands require a pair of keystrokes. Either 
or both of these may be a combination keystroke; for example, 
c-x followed by c-s (more commonly written as c-x c-s) 
saves the currently displayed file. Combination keystrokes are 
often grouped so that all those with the same first keystroke 
belong to a similar category of commands. For example, all 
keystrokes beginning with c-x involve opening and saving files 
or quitting Emacs, much like the choices on the File menu of 
most windowed operating systems' applications. 

Sometimes the first of a pair of keystrokes displays a menu of 
potential second keystrokes. For example, pressing C-h dis- 
plays the following in the minibuffer: 

c-h (Type ? for further options) 

(As we'll see in the "Available On-line FHelp" section, press- 
ing the ? key then gives you a description of your options.) 
PSGML makes good use of this type of prompt so that you 
don't need to memorize many keystrokes. 

Emacs can do so much that there are not enough keystrokes 
to go around, so it offers a command line where you can enter 
commands. Press M-x (Escape followed by the x key) to dis- 
play this command line in the minibuffer. This minibuffer com- 
mand line is important to an add-in package such as PSGML 
that adds customized features to Emacs for the benefit of a spe- 
cialized audience. 

For example, the goto-iine command has no keystroke to 
invoke it — we'll see in the section "Customizing Emacs" how 
to assign one — but you can jump the cursor to a specific line 
number by invoking the minibuffer command line with m-x, 
entering goto-line in the minibuffer, and pressing Enter. 
When Emacs prompts you with 

Goto line: 

at the minibuffer, enter the line number and press Enter. 
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With all of these multi-step command possibilities, it's good 
to know that a keystroke is available to abort one that you 
didn't mean to start: c-g. For example, if you press c-x, Emacs 
displays the following in the minibuffer to show that it's waiting 
for you to finish what you started: 

C-x- 

If you meant to press c-s instead of c-x, you couldn't press 
it now because c-x c-s is a very different Emacs command 
from c-s . 

if you actually follow through on a command that you didn't 
mean to execute, pressing c-_ (or selecting Undo from the Edit 
menu) undoes the most recent command. 

There's one more common trouble spot to be aware of. 
Heavy use of the Escape key means occasionally pressing it 
twice in a row by accident. This invokes a command so eso- 
teric that some UNIX versions of Emacs display the following: 

You have typed ESC ESC, invoking disabled command eval-expression: 

Evaluate EXPRESSION and print value in minibuffer. 

Value is also consed on to front of the variable 'values' . 

You can now type 

Space to try the command just this once, 

but leave it disabled, 
Y to try it and enable it (no questions if you use it again) , 
N to do nothing (command remains disabled) . 

Emacs is telling you "You just invoked an esoteric disabled 
command that you probably didn't mean to use. Do you really 
want to go through with this?" Enter n. Entering Esc Esc using 
other versions of Emacs just shows 

ESC ESC 

in the minibuffer; enter c-g to abort this. 
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Moving Your Cursor Around 

Most versions of Emacs support the regular cursor up, down, 
left, and right keys, c-Left and c-Right to move a whole 
word left or right, and the Page Up and Page Down keys for 
scrolling a screenful of text at a time, if you have problems with 
these keys — for example, if you use Emacs on a UNIX system 
from a PC over a phone line and your telecommunications pro- 
gram treats Page Down as the "start downloading a file" com- 
mand — you can use the original Emacs cursor movement keys 
from the days before computer keyboards had any cursor or 
Page Up and Page Down keys. The following list includes the 
Emacs commands invoked by these keystrokes because on-line 
help and Emacs documentation sometimes refer to them by 
these names instead of the keystrokes. 



C-p 


cursor up 


previous- line 


C-n 


cursor down 


next-line 


C-b 


cursor left 


backward- character 


C-f 


cursor right 


forward-character 


M-b 


word left 


previous -word 


M-f 


word right 


next-word 


M-v 


page up 


previous-page 


C-v 


page down 


next-page 



The following keystrokes are also handy for getting around 
quickly: 

C-a beginningof beginning-of-line 

current line 
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C-e end of cur- end-of-line 

rent line 

M-< beginningof beginning-of-buf f er 

file in cur- 
rent buffer 

M-> end of file in end-of-buf f er 

current 
buffer 

Editing and Deleting Text 

To enter text, simply move your cursor to the place where 
you want the new text and start typing. If you create a brand 
new document, the beginning of that document is the only 
place to enter it. 

If you type to the end of a line and continue typing, you may 
see a backslash ("\") appear as the last character of the line, 
and then your typed text appears on the second line: 

Returning to the Spouter-Inn from the Chapel, I found Queequeg there quite alon\ 
e; he having left the Chapel before the benediction some time. 

The backslash shows that your text isn't really continuing on 
the second line; the line is too long to appear on one line of 
your screen (or window), so Emacs just wraps its appearance so 
that you can see what you're typing. 

Of course, you can press Enter at any time to start a new 
line, but any decent word processor gives you the option of let- 
ting it automatically insert a carriage return at the last possible 
place before the cursor reaches the right margin. If you want 
Emacs to do this, enter m-x to bring up its command prompt 
and enter auto-f iii-mode. This turns on the "Fill" minor 
mode; the word "Fill" appears on the mode line to let you 
know that it's on (see Fig. 2.2). 
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Figure 2.2. Mode line showing that fill mode is on 

What if you're a programmer and you don't want your text 
editor to combine your program code into paragraphs? How do 
you turn fill mode off? The same way you turn it on: by entering 
auto-fill-mode at the M-x prompt. This command is known 
as a toggle because entering it when the mode is on turns it off, 
and entering it when the mode is off turns it on. 

To reset the right margin (or, in Emacs parlance, the "fill col- 
umn"), enter c-u followed by a number indicating the desired 
width of the text and then c-x f . 

To delete the character at the cursor, the Delete key should 
work, but if not, C-d does the same thing. Your Backspace key 
should also work. 



<TIP> When using a UNIX system, especially from a PC running a 
terminal emulation program, the Delete key is often the one 
that deletes the character to the left of the cursor, and c-d is 
your only option for deleting the character at the cursor. Or, 
Backspace deletes the character before the cursor and the 
Delete key does nothing, so that c-d is still your only option 
for deleting the character at the cursor. I'll refer to the key 
that deletes the character at the cursor as the Delete key and 
the one that deletes the character just before the cursor as the 
Backspace key, regardless of which keys on your keyboard 
perform these functions. 



To delete from the cursor position to the end of the line, 
press c-k (kill-line, a slightly misleading command name 
because it kills the line from the cursor position to the end, not 
the entire line). 
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One great feature of Emacs is its ability to re-justify para- 
graphs. For example, imagine that you typed a paragraph of 
text but then deleted a short sentence in the third line of that 
paragraph, and now you have a big gap in your right margin: 

He made me a present of his embalmed head; took out his enormous 
tobacco wallet, and groping under the tobacco, drew out some thirty 
dollars in silver; then spreading them 

on the table, and mechanically dividing them into two equal portions, 
pushed one of them towards me, and said it was mine. 

With your cursor at any point in that paragraph, press M-q 
(fill-paragraph) or select Fill from the Edit menu to adjust 
the paragraph to look like this: 

He made me a present of his embalmed head; took out his enormous 
tobacco wallet, and groping under the tobacco, drew out some thirty 
dollars in silver; then spreading them on the table, and mechanically 
dividing them into two equal portions, pushed one of them towards me, 
and said it was mine. 

This is a typical feature in word processors, but not in text 
editors, most of which are designed for programmers who deal 
in lines instead of paragraphs, fill-paragraph combines all 
the text between the last blank line before the cursor and the 
next blank line after the cursor into a new paragraph, if Emacs 
combines more text into a paragraph than you wanted, you can 
undo it with the c-_ undo command. 

A handy feature for adding a large amount of text is the abil- 
ity to insert an existing text file's contents at the cursor loca- 
tion. To do this, press c-x c-i and enter the filename at the 
minibuffer prompt: 

Insert file: c:\pathname\ 

if you don't want to insert a file from the current directory, 
backspace over the pathname displayed and enter the appro- 
priate one. 
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Saving Edits 

To save the file you're currently editing with the name 
already assigned to it, enter c-x c-s (or select Save Buffer 
from the Files menu) to invoke the save-buf fer command. To 
save it v\/ith a nevj name, enter c-x c-w (or select Save Buffer 
As... from the Files menu) to invoke the write-fiie com- 
mand. Emacs will ask you to enter the new name. If you like, 
you can backspace over the displayed path name and enter a 
new one: 



Write file: c: /pathname/ 



Copying, l\/loving, and Deleting Bloclcs of Text 

Emacs lets you copy, move, and delete user-defined blocks 
of text with operations similar to the cutting, copying, and past- 
ing of most popular word processors and text editors. However, 
its roots in the bronze age of computers mean that the vocabu- 
lary describing these operations may seem strange to the mod- 
ern user, so a brief glossary is helpful: 

region A block of text, 

point The cursor's location. 

mark If before the point, the start of a region; if after, 

the end of a region. 

kill ring A temporary region of memory that stores text to 
move or copy later on. On more modern word 
processors this is often called the "clipboard," 
although a kill ring can hold multiple blocks of 
cut or copied text. 

kill-region The act of deleting a marked region and saving 
the text in a temporary buffer in the kill ring. On 
modern word processors this is known as cutting 
a block into the clipboard. 
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copy-region Copying the marked region into the kill ring. 

yank Copying the kill ring's most recent addition to 

the cursor location. Word processors using the 
clipboard metaphor call this "pasting" the clip- 
board's contents. 

Choices on the Edit menu that implement these features 
often use the more modern terminology. 

You begin a copy, move, or delete operation by indicating 
the block of text in question. With your cursor at the beginning 
of the text, press C-space (or C-@, both for the set-mark- 
command) to set the mark and then move your cursor to the end 
of the region. Or, start with one of these two keystrokes at the 
end of the region and move your cursor to the beginning. 

Some versions of Emacs highlight the currently selected 
region, but most don't, so it's easy to forget which text is 
selected. This can lead to trouble with the delete command, so 

the exchange-point-and-mark command (C-x C-x) makes 
it easy to check the region's current boundaries by jumping the 
cursor to the currently set mark and setting the point as the new 
mark. Press the double key combination again to return your 
cursor to its location before you exchanged the point with the 
mark, and you can then continue where you left off. Essentially, 
doing this command twice jumps your cursor to the region's 
other boundary and back again so that you can quickly see 
where that boundary is. 

To delete (or "kill") the region, press C-w or select Cut from 
the Edit menu, if you deleted a region accidentally, "yank" it 
out of the kill ring to put it back by pressing c-y. if you move 
your cursor before yanking this text, yanking it moves the text 
to the cursor's new location. (Another c-w removes the 
recently yanked text if you put it in the wrong place.) 
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The menu equivalent of the yank command offers you a bit 
more flexibility: choose Select and Paste from the Edit menu to 
display a cascade menu of your last few yanked or copied 
pieces of text. Select one of these and Emacs pastes it at the 
cursor's position. 

You can copy a region to the kill ring by selecting Copy from 

the Edit menu or by pressing the kill-ring-save keystroke: 
M-w. This has no effect on the file you are editing, but once the 
region's text is in the kill ring, you can yank it all you want to 
make multiple copies. 

With word processors that use the clipboard metaphor, cut- 
ting or copying text into the clipboard replaces anything that 
was already there. If you cut or copy something with the inten- 
tion of pasting it somewhere and then cut or copy something 
else before you get around to the planned paste operation 
(c-y), you've lost the original block of text. The Emacs yank- 
pop command (M-y) lets you replace the most recently yanked 
text with whatever was killed or copied into the kill ring before 
the text that you just yanked. (The "pop" part of the name is 
programmer's lingo for the operation performed on the data 
structure holding the killed and copied text.) Pressing M-y 
repeatedly continues to replace the recently yanked text with 
earlier and earlier versions of killed or copied text; how early 
you can go depends on the version of Emacs you're using. 
Once you pop the oldest kill ring item, the next pop inserts the 
most recent item saved in the kill ring. That's why it's called a 
"ring." 

For example, let's say you want to move the "red" line in the 
following text after the "blue" line. 

yellow 

red 

black 

white 

blue 

green 
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You move your cursor to the beginning of the "red" line and 
press c-space to indicate the beginning of a block. Then, you 
move your cursor to the beginning of the line below it and 
press c-wto kill that marked line. 



yellow 

black 

white 

blue 

green 



yellow 
black 
blue 
green 



yellow 

black 

blue 

white 

green 



As you move your cursor toward the "red" line's new loca- 
tion, you realize that you didn't want the "white" line there at 
all, so you kill it with the same keystrokes. 



You continue the cursor's journey to the "red" line's new 
location and put it at the "g" in "green" because "red" will be 
inserted before the "green" line and after the "blue" line. You 
press C-y to yank the kill ring text to the cursor's location and 
reel back in horror as you realize that you pasted the "white" 
line there, not the "red" line: 



Before rending your clothing in anguish over your mistake, 
you remember the yank-pop command, which yanks earlier 
kill ring contents to the cursor location. You press M-y and the 
"red" line replaces the mistakenly yanked "white" line. 
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yellow 

black 

blue 

red 

green 



Searching for Text, Replacing Text 

The most common Emacs search is known as an "incremen- 
tal search." Enter C-s and start typing your search target at the 
minibuffer's i-search: prompt and notice how the cursor 
jumps to the first place that matches your search target as you 
type each character. For example, let's say we want to search 
for the word "hazel" in the following. After the "W is typed, the 
cursor immediately jumps to the first character after the first 
"h" it finds, as shown in Fig. 2.3. 



Dhfl sweet friends* Hearken to ne. It uas made of small juicy clans, 
scarcely bigger than hazel nuts, mixed iiith pounded ship biscuit, and 
salted pork cut up into little flakes; the whole enriched uith butter, 
and nl fnti f 111 1 M spn^nnprl uith npnper and salt. 



Emacs: Mhalin.sqn (SGML [chapter] Fill Isearch) — L5B— IV- | 



|l-searcli: h 



Figure 2.3. Incremental search after the first character is entered 

After typing the letter "a," the cursor jumps to the "n" in 
"than," the first character after the first occurrence of "ha" (see 
Fig. 2.4). 



Oh, sweet friends' Hearken to me. It Has Hade of snail Julcjp clans, 

scarcely bigger thaQ hazel nuts, mixed with pounded ship biscuit, and 
salted pork cut up into littlp flakps; the whole enriched with butter, 
and plentifully seasoneij with pepper jnd salt. 



Enacs: whalin.sqm (SGML [chapter] Fill Isearch)— L51— 



ll-search: ha I 



Figure 2.4. Incremental search after second character entered 

Type a "z," and the cursor jumps to the "e" after the "haz" in 
"hazel," as shown in Fig. 2.5. 
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Oh, sweet friendst Hearken to rae. It was made of snail juicy clans, 
scarcely bigger than hazQl nuts, mixed with pounded ship biscuit, and 
salted pork cut up into little flakes; the whole enriched with butter. 




Figure 2.5. Incremental search after third character entered 

If you enter a series of characters that Emacs can't find, it 
tells you in the minibuffer. For example, if you type the letter 
"x" at the end of the "haz" entered so far, the minibuffer mes- 
sage tells you this: 

Failing I-search: hazx 

if you've found the string that you're looking for but want 
Emacs to look for another occurrence of it, press c-s again. 
When you've done enough searching, press Enter to stop the 
incremental search. 

Another handy key \Nhen searching is the Backspace key. 
Using it to delete the most recent key in the minibuffer returns 
the cursor to its most recent search hit. For example, if you 
backspace over the "z" after Emacs found the v\/ord "haz" in 
the above example, the cursor jumps back to the "than," 
which has the first example of the "ha" string currently show- 
ing in the minibuffer. 

Searching backward is similar to searching forward except 
that you begin an incremental reverse search with the key- 
stroke C-r. For each character you add to the search string, 
Emacs jumps the cursor to the file's most recent occurrence of 
the current search string until you either enter a string it can't 
find or press one of the keystrokes that tells it to stop looking 
(for example. Enter). As with a forward search, the Backspace 
key also deletes the most recent character in the search string, 
jumping the cursor back to its location before you entered that 
character. 
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Emacs has several commands that can perform a search and 
replace operation. The most versatile is query-replace, 
which you invoke v\/ith the m-% keystroke or the Query 
Replace... choice of the Search menu. Press it and Emacs dis- 
plays the following prompt in the minibuffer: 



Query replace: 



Enter the string to replace and press Enter. For example, 
let's say you entered "my fault." The minibuffer then asks you 
to enter the replacement string: 



Query replace my fault with: 



Enter the replacement string (we'll change "my fault" to 
"your fault") and press Enter. Emacs then tries to find the 
search string. If it doesn't, it displays the message Replaced 0 
occurrences in the minibuffer; if it does, it moves the cursor 
to the first occurrence and displays the following prompt: 



Query replacing my fault with your fault: (? for help) 



Enter ? to display a list of options. The following shows the 
most important ones: 

y Replace this entry and search for the next one. 

The space bar has the same effect. 

n Don't replace this entry, but skip to the next one. 

q Don't replace this entry. Stop looking. 

! Replace all remaining occurrences of the search 

string, no questions asked. 
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Editing Multiple Files 

The c-x c-f command invokes the find- file command. 
Entering it (or selecting Find File... from the File menu) tells 
Emacs "Edit the file whose name I'm about to give you. If it's 
already in a buffer, shovj me that buffer; if it's not in a buffer 
but on a disk, read it into a buffer where I can edit it; if it's not 
there either, create a buffer that I can treat as a new file." In the 
minibuffer, Emacs then asks you for the name of the file to edit, 
substituting your current directory for pathname: 

Find file : c : \pathname\ 

If the file you want is in that directory, just enter its name. 
Otherwise, edit the pathname by deleting characters with the 
backspace key or adding new characters before entering the 
filename. If you can't remember the filename, we'll see how to 
list the files in the current directory in a separate window and 
pick one from the list using Emacs's "completion" features 
described in the next section. 

To switch from one active buffer to another, enter c-x b for 
the switch-to-buffer command. Emacs prompts you for the 
buffer's name, which is the same as the name as the file in that 
buffer. As with find-file, you can use the "completion" fea- 
ture if you don't know the current buffer names. 

All buffers share the same kill ring, which makes it easy to 
copy and move text between them. For example, to move a 
paragraph from f iiei . txt to f iie2 . txt, you would: 

1. Markaregionoftextinfiiei.txt. 

2. Kill it with the c-w keystroke. 

3. Display the other file by entering c-x b and answering the 
Switch to buffer: minibuffer prompt with file2.txt. 

4. Move your cursor to the insertion point in fiie2.txt 
with the cursor movement keys or by using c-s to search 
for a string that you know is near the insertion point. 
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5. Insert the text from the kill ring with c-y . 

While viewing a particular buffer, pressing c-x c-s tells 
Emacs to save the file in that buffer. It's not unusual when you 
have several files open in different buffers to save the current 
one and then try to quit Emacs without saving the others; that's 
why Emacs displays a reminder if you enter c-x c-c to quit 
when you still have unsaved work. 

Completion 

when Emacs is waiting for you to enter information and 
you're not sure what to enter, or you don't feel like typing in all 
those keystrokes, Emacs can do a lot of the typing for you. 

For example, the last section showed you how c-x c-f can 
tell Emacs to open a new buffer for a new file. Let's say you 
want to edit a file on your hard disk's current directory and you 
remember that the filename begins with the letters "apr" but 
can't remember the rest. After you press c-x c-f and enter 
"apr" in the minibuffer, pressing the Tab key tells Emacs to fill 
in as many of the remaining letters as possible. If only one file 
begins with these letters, it finishes the file's name; if more than 
one such file exists, Emacs fills in as many as it can. For exam- 
ple, if there are files named aprii95.txt and aprii96.txt 
in the current directory, and you enter "apr" and press Tab, 
Emacs adds the "il9" because the two files that begin with 
"apr" both begin with the letters "april9." It also splits the win- 
dow and lists the files whose names fit this pattern, as shown in 
Fig. 2.6. 

You can then type in the remainder of the name, or, as the 
new window tells you, you can move your cursor to the name 
you want and press "Ret" (the Return or Enter key). We'll see 
in the next section how to move your cursor from one window 
to another and how to delete a window when you're done with 
it. 
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Click nouse-2 on a completion to select it. 

In this buffer, type RET to select the completion near point. 



Possible completions are: 
BPRIL95.TXT 



april96.txt 



Find file: C:\april9| 



Figure 2.6. Possible completions to the sample find- file command 



Completion is used for entering more than just filenames. 
When entering a long Emacs commancJ such as add-change- 
log-entry-other-window at the M-x prompt, you can type a 
few characters, press Tab, type a couple more to make it more 
unique, press Tab again, and continue with this process until 
you have the complete command name. Completion also helps 
you to enter buffer names after entering c-x b to switch to a 
buffer whose name you can't remember, as well as variable 
names, which we'll learn about in the "Customizing Emacs" 
section. 



Using Multiple Emacs Windows 

You can split the Emacs screen into two or more regions 
known as "windows" to look at multiple buffers at once. (Don't 
confuse these with the windows used for the operating system 
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interface in Microsoft Windows, UNIX X-Windows, or the 
Macintosh — this doesn't create new independent screen rect- 
angles but instead splits the current one.) Sometimes Emacs 
splits the screen automatically to simultaneously show you the 
currently active buffer as well as some other information, such 
as on-line help or a list of potential completions to text you've 
entered. Even if you have no plans to split the screen into two 
windows yourself, you should learn the commands that manip- 
ulate multiple windows in order to give you better control over 
the Emacs environment when Emacs splits its default main 
screen for one of these reasons. 

Entering c-x 2 (or selecting Split Window from the Files 
menu) splits the Emacs screen horizontally into two windows. 
Both windows display the buffer that you were looking at when 
you pressed c-x 2; all commands that we've seen for specify- 
ing files and buffers to work on will then apply to the window 
with the cursor in it. 

So, to look at two different files at once, you would: 

1 . Display one of the files using a method we've already 
seen. 

2. Enter c-x 2 to split the screen. 

3. Enter c-x c-f to retrieve the second file into one of the 
two windows. 

When the screen is divided into multiple windows, the key- 
stroke c-x o (note that this uses the letter "o," not the digit 
zero — as we'll see, c-x o has a very different effect) moves the 
cursor to the next, or "other," window. If there is something in 
the minibuffer, this counts as a little window. So, when viewing 
Fig. 2.6, which shows the cursor in the minibuffer, pressing 
C-x o moves the cursor to the top window, as shown in 
Fig. 2.7. 
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Click mouse-2 on a completion to select it. 

In this buffer, type RET to select the completion near point. 



Possible completions are: 
ftPRIL95.TXT 



Find file: C:\april9 




april96.txt 



Figure 2.7. Moving the cursor to the next window with the other- 
window command 



Pressing it again moves it to the lower wincJow (see Fig. 2.8). 

Pressing it a third time moves it back to the minibuffer. 

Now we know how to create and navigate among these win- 
dows. How do we get rid of them? The c-x 0 keystroke exe- 
cutes the deiete-window command, which deletes the 
cursor's current window. (This is the C-x zero command men- 
tioned earlier, not to be confused with c-x o.) Think of it as 
"zeroing out" the cursor's current window. 
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glick nouse-2 on a completion to select it. 

In this buffer, type RET to select the completion near point. 



Possible completions are: 
BPRIL95.TXT 



april96.txt 



Find file: C:\april9 



Figure 2.8. Moving to another window with the other-window 
command 



The c-x 1 keystroke (and the One Window choice of the 
Files menu) executes the deiete-other-windows command, 
which expands the cursor's current window and deletes the 
others. Think of it as "make this window the only one" to help 
remember it more easily. 

If any deleted windows held file buffers, those buffers are 
still around, they're just not displayed — you can always switch 
to another with c-x b. 

A similar keystroke is available when you want to switch 
buffers but don't remember their names: C-x c-b, the list- 
buffers command, if necessary, this splits the current window 
and lists the currently existing buffers in the other window. 
Press c-x o to move your cursor to this list, move it to the 
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name of the buffer you want, and press the number l to display 
that buffer in the window where the cursor was when you first 
pressed C-x c-b. 

The Buffers menu also lists the current buffers; select one to 
put that buffer in the cursor's window. 

Customizing Emacs 

Emacs lets you store a series of keystrokes for later playback, 
which is handy when you're tired of repeatedly pressing the 
same series of keystrokes, it also lets you customize the envi- 
ronment by writing programs in the Emacs LISP programming 
language. Even if you've never used LISP or one of its descen- 
dants (such as Scheme or CLOS), you can easily make minor 
changes to other users' programs to gain greater control over 
your own use of Emacs. 

Recording and Executing Macros 

Emacs offers a keyboard macro facility that lets you record 
and play back keystrokes. You begin and end your "recording" 
of the keystrokes by entering c-x followed by one of the paren- 
theses characters. The c-x ( keystroke, for start-kbd-macro, 
tells Emacs to record the upcoming keystrokes, and c-x ), for 
end-kbd-macro, tells Emacs to Stop recording. 

Pressing c-x e executes the call-last-kbd-macro com- 
mand. This executes the macro most recently defined with 
c-x ( and c-x ) . 

If you create a macro and want to create another without losing 
the ability to execute the first one, you can name the first one by 
pressing M-x and entering the name-iast-kbd-macro command 
at the minibuffer prompt. After you press Enter, Emacs asks you for 
the macro's name; if you name it testmacro, you can then record 
and use another macro and still invoke testmacro the same way 
you would use any other Emacs command: by entering it at the m-x 
minibuffer prompt. 
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As soon as you quit Emacs, you lose the most recently 
named macro and any other named macros saved during that 
session. What if you want to define macros to use perma- 
nently? At the end of this section, after we've covered the 
basics of the .emacs customization file, we'll see how to add 
named macros so that you can use them in the future. 

Emacs LISP 

More serious Emacs customization is done by writing Emacs 
LISP programs. These don't have to be complicated. For exam- 
ple, assigning an Emacs command to a particular keystroke can 
be done with one line of LISP code. 

In the LISP programming language, as with C, everything is 
defined as a function. You can write your own functions or use 
collections written by other people known as "packages" to 
customize Emacs's behavior. PSGML is a LISP package, but 
before we get to that, we'll start with a simpler collection of 
LISP functions: the automatic startup functions stored in the 
.emacs (pronounced "dot emacs") file. 



<TIP> Because DOS won't allow filenames that begin with a period, 
DOS and 16-bit Windows versions of Emacs usually use the 
name _emacs for the file of automatic startup functions. 

While the syntax of the .emacs functions may seem odd to 
someone with no experience in LISP or its descendants, you 
can write your own LISP functions by merely taking others and 
changing the crucial parts. For example, let's say I see the fol- 
lowing line in someone's .emacs file to set M-g to invoke the 
goto-line command: 

(global-set -key "\eg" 'goto-line) ; M-g prompts for line number to enter 
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The goto-iine command is normally not invoked by (or 
"bound to," as the Emacs types say) any key, so that you need 
to enter m-x and then goto-iine at the minibuffer command 
prompt in order to go to a specific line by its number. Program- 
mers and SGML people often run programs that identify prob- 
lems in program and data files by their line numbers, so they 
need to use Emacs's goto-iine command so often that it 
would be easier to just press a key or two to invoke it. 

Copy the giobai-set-key line shown above into your 
.emacs file and quit and restart Emacs. From that point on, 
pressing M-g displays a Goto line: prompt in the minibuffer, 
which waits for you to tell Emacs where to put the cursor. 

Another command popular with PC word-processor users is 
overwrite-mode, which toggles Emacs between insert and 
replace modes. In other words, entering this command at the 
M-x prompt puts Emacs in replace mode if you were already in 
insert mode, so that typed characters replace existing charac- 
ters at the cursor, or it puts you in insert mode if you're already 
in replace mode, so that newly typed characters move any 
existing characters on the cursor's right further to the right. 

PC users are accustomed to this toggling behavior from their 
Insert key and don't necessarily want to bring up a command 
line and enter a 14-letter command, it would be nice to define 
a LISP function in the . emacs file that assigns this command to 
the M-i keystroke. Let's look closer at the line that assigned the 
goto-iine command to the M-g keystroke and see which 
parts to keep and which we can change in order to create a 
LISP function that gives M-i the behavior we want. 

LISP functions are usually in the form of a list (the name 
actually means "List Processor") within parentheses. The first 
item in the list is the function name; the number and role of the 
remaining items depend on which function starts the list. 

The Emacs LISP global-set-key function sets a particular 
key to perform an Emacs function. (Non-global versions specify 
key assignments that only work in certain modes.) This takes 
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two parameters: the key to set and the command to assign to it. 
You'll rarely assign a command to a single letter or number on 
your keyboard; as with most Emacs commands, these new 
commands are invoked by some combination of a letter or a 
number with the Escape or Ctrl key. 

To assign a key to be pressed after the Escape key, precede it 
with a backslash and the letter "e." For example, we saw that 
binding M-g to invoke the goto-iine command meant assign- 
ing that command to the "\eg" keystroke combination. 

Also, remember to put an apostrophe (or, in programmers' 
parlance, a "single quote") before the command name being 
assigned to the keystroke. In LISP, this makes the command 
name a symbol. Don't worry about LISP symbols unless you 
want to get heavily into LISP; just remember to include it when 
assigning commands to keystrokes. 

One more thing: when Emacs executes LISP code, it ignores 
a semicolon and anything after it, so use these to insert com- 
ments. This makes it easier to remember why you wrote what 
you did, and it also makes it easier to learn from other Emacs 
LISP programs out there — assuming the programs have been 
commented. 

So, putting this all together, we can set up the M-i keystroke 
to toggle between insert and replace mode by adding the fol- 
lowing line to our .emacs file: 

(global-set -key "\ei" ' overwrite-mode) ; toggle oveirwrite mode 

Assigning a command to a Ctrl key combination requires a 
new Emacs trick: the quoted-insert command, entered with 
c-q. This tells Emacs to treat the next character you type as a 
character to be inserted into the buffer, even if Emacs normally 
treats it as a command. So, while c-a normally means "move 
my cursor to the beginning of the current line," pressing 
c-q c-a means "insert the C-a character at the cursor posi- 
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tion." It shows up as ^A, but most programs that do anything 
with this file treat it very differently from something entered 
with the character (shift 6) followed by the letter "A." 

This includes Emacs. To put this to use, let's assign the c-t 
keystroke to execute the kill-word command, which deletes 
text from the cursor's position to the next word ending. (This 
shows my age — I got used to this command when Wordstar 
was the most popular PC word processor and "32-bit" meant a 
refrigerator-sized minicomputer. M-d is the built-in Emacs key- 
stroke that kills the next word.) 

Add the following line to your .emacs file to make this com- 
mand available: 

(global-set -key '""T" 'kill-word) ; enter -^T here with C-q C-t 



Setting Emacs Variables to Controi Its Behavior 

Another common reason to edit your .emacs file is to 
change the value of variables. Programs use variables to keep 
track of values, and you can change the behavior of your copy 
of Emacs by changing the value of its built-in variables. 

Some variables keep track of numeric values. For example, 
next-screen-context-lines keeps track of how many lines 
of a given screen remain when you press a Page Up or 
Page Down key. When it's set to 2, the bottom two lines 
become the top two lines when you page down, and the top 
two lines become the bottom two when you page up. To check 
a variable's value, enter c-h v and then the variable's name. 

You can change the value of such variables by entering m-x 
and then entering set-variable at the Emacs command line. 
Press Enter, and Emacs prompts you for the name of the vari- 
able to set. After entering its name and pressing Enter again, 
Emacs prompts you for the variable's new value. 
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This is a lot of steps, especially for a variable with a name as 

long as next-screen-context-lines, if you want tO set this 
value to 1 every time you start up Emacs, use the Emacs LISP 
setq function to automate this by adding the following line to 
your .emacs file: 

(setq next-screen-context-lines 1) 

Not all variables hold numeric values; some, like load- 
path, hold strings of characters, load-path is a list of subdi- 
rectories in which Emacs looks when you tell it to load a file of 
LISP code. As we'll see in the section "Editing SGML Docu- 
ments with Emacs and PSGML," you'll need to reset load- 
path for Emacs to find PSGML. 

Many Emacs variables are Boolean. A Boolean variable 
(named for the 19th-century British mathematician George 
Boole) is like a switch that can be turned on or off, and while 
beginning programmers rarely use them in their programs, the 
ability to set Emacs's many Boolean variables gives you a great 
deal of freedom in customizing its behavior. For example, your 
copy of Emacs may or may not do case-sensitive searches 
when you execute an incremental search with c-s or c-r. (A 
case-insensitive search finds the character strings "HELLO" or 
"hello" when you tell it to search for "Hello"; a case-sensitive 
search only finds an exact match.) 

You can control case sensitivity by setting the case-fold- 
search variable. To tell Emacs to ignore case when searching, 
add the following line to your . emacs file: 

(setq case-fold-search t) 

To set your default to case-sensitive searching, set the vari- 
able off with this line: 

(setq case-fold-search nil) 
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Other programming languages use "true" and "false" or 1 
and 0 to turn Boolean variables on and off. Emacs uses nil to 
turn Boolean variables off for reasons that have more to do 
with LISP than with Emacs; the t is just a convention, because 
anything other than nil assigns a true value. (This is similar to 
the C-related languages' use of 0 to represent "false" and any 
other number to represent "true.") Remember this when read- 
ing Emacs documentation, which rarely tells you to set a vari- 
able to "t" — it's more (mathematically) proper because it tells 
you to set a Boolean variable to nil for one kind of behavior or 
to a "non-nil" value otherwise. Use t for this. 

To store a keyboard macro definition in your .emacs file so 
that you can use that macro without ever needing to redefine it, 
the insert-kbd-macro command adds the Emacs LISP equiv- 
alent of the macro definition to the current buffer. Let's look at 
an example. 

A handy macro for SGML people is one that speeds the entry 
of comments. To define a macro, first enter c-x ( to tell 
Emacs to start recording a macro, and then enter the characters 



followed by four cursor-left keystrokes, which put the cursor 
where you can start typing the comment. Next, enter c-x ) to 
tell Emacs to stop recording. 

Name your macro by pressing m-x and entering name- 
last-kbd-macro at the prompt in the minibuffer. A good 
name would be sgml- comment. 

Next, edit your . emacs file, or its equivalent in the operating 
system you're using, and move your cursor to a blank line 
where you want the macro definition. Press m-x to bring up the 
minibuffer prompt and enter the insert-kbd-macro com- 
mand. When Emacs asks which macro to insert, type sgml- 
comment. You'll see the following appear at the cursor: 

(fset ' sgml-coinment [?< ?!?-?-? ? ?- ?- ?> left left left left]) 
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Now you have a new command in your Emacs environment 
called "sgml-comment." Since typing this at the command line 

is no easier than typing out "<\ >" every time you want to 

enter a comment, you'll want to assign this new command to a 
keystroke, so add the line 



(global-set-key "'^Co" 'sgml-comment) 



to assign it to the c-c o keystroke. (I chose this because "c" 
and "o" are the first two letters in the word "comment" and 
because this keystroke combination is not bound to any exist- 
ing Emacs function. Remember to enter c-q before entering 
c-c so that the c-c character is inserted into your .emacs file. 
Enter the "o" as you would normally.) Make sure to save your 
.emacs file. Quit out of Emacs, start it up again with a test file, 
and enter c-c o to see your new saved macro in action. 



Available On-line Help 



Emacs offers extensive on-line help, all available by pressing 
the c-h key. This displays the following prompt in the 
minibuffer: 



c-h (Type ? for further 
options) - 



Emacs offers so many categories of help that you need to tell 
it which category you're interested in seeing, if you don't know 
the categories, enter a question mark and Emacs splits the 
screen, if necessary, to show you descriptions of the various 
kinds of available help (see Fig. 2.9). 
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<para>hlext norning, Monday, after disposing of the embalmed head 
to a barber, for a block, I settled my oun and comrade's bill; using, 
howeuer, my comrade's money .</para> 
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Vou haue typed C-h, the help character. Type a Help option: 

(Use SPC or DEL to scroll through this text. Type q to exit the Help command 

a command-apropos. Giue a substring, and see a list of commands 

(functions interactiuely callable) that contain 

that substring. See also the apropos command, 
b describe-bindings . Display table of all key bindings, 
c describe-key-briefly. Type a command key sequence; 

it prints the function name that sequence runs. 
Q describe-f unction . Type a function name and get documentation of it. 
C-f Inf o-goto-emacs-command-node . Type a function name; 

it takes you to the Info node for that command. 
F uieu-emacs-FflQ . Shous emacs frequently asked questions file, 
i info. The info documentation reader. 



Type one of the options listed or Space to scroll: 



Figure 2.9. Emacs's description of various help categories 



There are so many help categories that they won't fit on the 
screen. Instead of trying to memorize them all, start with the 
most important ones, and remember that you can always press 
c-h ? to learn more. 

a (command-apropos) 

List all the commands with a given string of char- 
acters in them. For example, enter c-h a and 
then the word "macro" in response to the Com- 
mand apropos (regexp) : prompt in the 
minibuffer. Fig. 2.10 shows how the help facility 
lists all the commands that involve creating and 
using macros (with their keystrokes if any have 
been assigned). 
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Buffers Files Tools Edit Search SGML Modify Move Markup View DTD Help 
there . ' </pai-a> 
</sect1> 
<sect1> 

<title>Biographical</title> 

<pai'a>Queequeg uas a natiue oF <enphasis>Kokouol<o</enphasis> , an 
island Far auay to the West and South .</para> 

I <para>It is not doun in any map; true places neuer are.</para> 
</sect1> 
<sect1> 

<title>Wheelbarrow</title> 

<para>ffext norning, Monday, aFter disposing oF the embalmed head 
to a barber. For a block, I settled ny oun and comrade's bill; using, 
houeuer, mg comrade's money .</para> 
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moue to the beginning 



Click mouse-2 to get Full documentation. 
In this buFfer, type RET to get Full documentation. 

apply-macro-to-region-lines (not bound to any keys) 

Command: For each complete line between point and mark, 
call-last-kbd-macro C-x e 

Command: Call the last keyboard macro that you deFined with C-x (. 
deFining-kbd-macro (not bound to any keys) 

Command: Record subsequent keyboard input, deFining a keyboard macro, 
edit-kbd-macro C-x C-k 

Command: Edit a keyboard macro, 
edit-last-kbd-macro (not bound to any keys) 

Command: Edit the most recently deFined keyboard macro, 
edit-named-kbd-macro (not bound to any keys) 

IIIIII^^M»l|i|||||||||<IIIMIHIII 



Type C-x 1 to remove help uindou. M-C-u to scroll the help. 



Figure 2.10. command-apropos entries for "macro' 



Selecting Command Apropos... from the Help 
menu also invokes this command. 

C-h k (describe-key) 

After you press C-h k, press any Emacs key- 
stroke to display on-line help about that key- 
stroke. This is useful for deciding which 
keystroke is free to have a macro assigned to it. 
For example, pressing c-h k c-a displays the 
screen shown in Fig. 2.11. 

Selecting Describe Key... from the Help menu 
does the same thing. 
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Buffers Files Tools Edit Seaich SGML Modify Move Markup View DTD Help 
</sect1> 

<sect1> 

<title>Wheelbart-ow</tltle> 

<para>Next norning, Monday, after disposing of the embalmed head 

to a barber, for a block, I settled my oun and comrade's bill; 

using houeuer, mij comrade's money .</para> 
</sect1> 
<sect1>| 

<title>Biographical</title> 

<para>Queequeg uas a natiue of <emphasis>Kol<ouol<a</emphasis> , an 
island far auay to the Uest and South .</para> 
<para>It is not doun in any map; true places never are.</para> 
<para>It uas on a Saturday night in December .</para> 
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C-a runs the command beginning-of -line : 
Moue point to beginning of current line. 

With argument ARG not nil or 1, moue forward ARG - 1 lines first. 
If scan reaches end of buffer, stop there without error. 

(beginning-of-line ^optional N) 



Figure 2.1 1. describe-key information on C-a 



C-h t (help-with-tutorial) 

Start the interactive Emacs tutorial. This reviews 
the Emacs features that you read about here and 
teaches you some new ones. 

c-h V (describe-variable) 

Enter the name of an Emacs variable and the 
help system displays the variable's current value 
and any available documentation. This is useful 
to check on the necessity of resetting a variable's 
value. 
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C-h i (info) 

Start the info program, a menu-driven browser 
for Emacs documentation, as shown in Fig. 2.12. 



Buffers Files Toofs Edit Search Help 

File: die Node: Top This is the top of the INFO tree 
This (the Directory node) giues a menu of major topics. 
Typing "d" returns here, "q" exits, "?" lists all INFO connands, "h" 
giues a primer for first-timers, "mEmacs<Return>" visits the Emacs topic, 
etc . 

In Emacs, you can click mouse button 2 on a menu item or cross reference 
to select it. 

— PLEflSE ADD DOCUMENTATION TO THIS TREE. (See INFO topic first.) — 
» Menu: The list of major topics begins on the next line. 

Info: (info). Documentation brousing system. 

• Emacs: (emacs). The extensible self-documenting text editor. 
« UIP: (uip). A Ul-emulation for Emacs. 

• UIPER: (uiper). The new Ul-emulation mode in Emacs-19.29. 
» Forms: (forms). Emacs package for editing data bases 

by filling in forms. 

• GNUS: (gnus). The neus reader GNUS. 

• MH-E: (mh-e). Emacs interface to the MH mail system. 

• CL: (cl). Partial Common Lisp support for Emacs Lisp. 

» SC: (sc). Superclte lets you cite parts of messages you're 

replying to, in flexible uays. 
» Dired-X: (dired-x). Dired Extra Features. 

» Ediff: (ediff). A comprehensive visual interface to diff 6 patch. 
CC mode: (ccmode). The GNU Emacs mode for editing C, C**, Objectiue-C 
and Java code. 



(T:Info Narrow)— L27— All 



Figure 2.12. Emacs info opening screen 



The lines with asterisks are menu choices. Move 
your cursor to one and press Enter to select that 
choice. The "Info" choice is a good place to start 
in order to learn more about navigating the Info 
browser. The handiest Info command is ?, which 
displays the important single-letter Info naviga- 
tion commands. The most important of these is 
the letter i for "last node," which lets you retrace 
your path after selecting a series of Info nodes 
(information topics). 
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If your copy of Emacs has trouble finding the Info files, add 
the following line to your .emacs file to tell Emacs where to 
look, substituting the appropriate pathname for /path- 
name /emacs/: 

(setq 

Info-directory-list (cons 

"/pathname/emacs/info" Info-default-directory-list) ) 

Entering a question mark after you've entered c-h is like ask- 
ing for help about the help facility. After you've looked it over, 
you're still in the on-line help, and Emacs is still waiting for you 
to enter one of the other possible keystrokes (besides ?) that 
can come after c-h — such as a for command-apropos or i for 
info. 

Editing SGIVIL Documents with Emacs and PSGI\/IL 

Emacs actually has a built-in mode for editing SGML docu- 
ments, but it merely automates the insertion of tag delimiters 
("<" and ">") and the calling of the external program that can 
validate the file you're working on, such as nsgmls or sgmls. 

PSGML is an add-on SGML mode for Emacs which does 
much more. While not a complete SGML validator, it adds 
many features to Emacs that let you edit a document instance 
without worrying about its structure because it automates most 
of the tasks necessary to maintain that structure. In addition to 
letting you select and add the appropriate tags with a minimum 
of keystrokes, it can insert required tags automatically, help 
you find structural mistakes, indent tags to show nesting struc- 
ture, and let you set tags, comments, and entity references in 
different fonts or colors to make it easier to see the structure. 
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Installing PSGML 

A user usually receives PSGML as a collection of files com- 
bined into one compressed file such as a DOSAA/indows ZIP 
file or a UNIX GNU zip file. Files extracted from this distribu- 
tion file fall into three main categories: 

• Those that end with an extension of .el, which are collec- 
tions of LISP functions similar to your . emacs file. 

• Those with an extension of . eic, which are compiled ver- 
sions of the .el file that run faster. 

• All the other files, which contain information about install- 
ing and using PSGML. 

UNIX users will find installation instructions and scripts 
included with PSGML. DOSAA/indows users need to execute 
the important steps by hand. 

The . eic files created with one version of Emacs on a partic- 
ular operating system may not work with another version of the 
program or on another operating system, but you can create 
new ones yourself from the .el files. You can actually run 
PSGML using only the .el files, but it's so much faster with 
.eic files that you may as well create them before trying to use 
it. 

First, put all the PSGML files into their own subdirectory and 
make sure that Emacs knows where to find them by adding the 
following LISP code to your .emacs startup file: 

(setq load-path 
(append 

(list nil 

"/app/emacs/psgml") ; substitute your PSGML directory name 

load-path) ) 
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<TIP> Even when using Emacs and PSGML under DOS/Windows, 
PSGML expects the directory name to be entered with for- 
ward slashes ("/") and not the backslashes ("\") used in PC 
pathnames. 



This adds the directory name to the Emacs load-path vari- 
able, a list of directories where Emacs looks when you tell it to 
load a particular program. Substitute the name of the directory 
where you stored the PSGML files for /app/ emacs /psgmi 
above. 

Next, enter m-x to display the Emacs command line and 
enter byte-compile-f lie. Press Enter, and at the Byte 
compile f lie : prompt, enter the name of an . ei file to com- 
pile and press Enter. If the prompt is Byte compile file: 
-/, you can treat that -/ as the name of the current directory 
and then type psgmi/psgmi . el after it if you want to compile 
the psgmi.ei file in the psgmi subdirectory of your current 
directory. 

Do this for all the .ei files in your PSGML directory. If you 
see any error messages during the compilation of a file, com- 
pile the others and go back and try that one again. It may have 
relied on something from another .eic file that you hadn't yet 
created. 

A shortcut to repeatedly entering the byte-compiie-fiie 
command is the byte-force-recompile command, which 
prompts you for the name of a directory and then compiles all 
the .el files in that directory. 

1 mentioned that Emacs has a built-in SGML mode that 
doesn't do much, so the next step is to tell Emacs to use 
PSGML for its SGML mode instead of the built-in one. Do this 
by adding the line 

(autoload ' sgml-mode "psgmi" "Major mode to edit SGML files." t ) 
to your . emacs file. 
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In addition to the program files, PSGML includes documen- 
tation that you can view with the Emacs Info browser. Put the 
psgmi.info file into the directory (probably a subdirectory of 
the main Emacs directory called info) with the other Info files. 
Then edit the dir file in that same directory to include the fol- 
lowing line: 

* PSGML: (psgml) . SGML editing. 

If it's a multi-user system and you're not the system adminis- 
trator, you probably won't be allowed to add or edit files in a 
subdirectory of the Emacs directory. You can still view the 
psgmi.info file from within Emacs by putting it in any direc- 
tory you wish and entering the command 

C-h i g (/pathname/psgml . info) 

to display that file with the Info program. (Include the full path- 
name of its location where you see /pathname/.) 



<TIP> Remember to leave off the "o" in the file extension if you're 
using Emacs and PSGML under DOS^ where file extensions 
can only be up to three letters long. 

When specifying the info file's location, DOS/Windows Emacs 
accepts pathnames with forward slashes ("/") or backslashes 
("\") separating its components. 



Starting Up PSGML 

How does Emacs know to load PSGML mode? There are 
three ways: 

• It knows to automatically load it if you edit a file with an 
extension of ".sgml" or ".sgm." 
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• You can load a mode in Emacs by entering m-x and enter- 
ing the mode's name (in this case, sgmi-mode) at the 
minibuffer command line. This is valuable when editing 
SGML files that don't have ".sgml" or ".sgm" as an exten- 
sion. 

• The following line at the top of your file tells Emacs to 
automatically load PSGML: 



Once you start up Emacs with PSGML and load a document, 
PSGML doesn't actually parse the document (unless the 
sgml-auto-activate-dtd and sgml-set-f ace variables are 
both set to t) until you execute one of a certain category of 
commands. Because of this, it can't do any of the automatic 
visual formatting that makes editing your document easier — for 
example, indenting of the element nesting levels or displaying 
markup in different fonts or colors. One of the commands that 
causes it to parse, and a good one to start with, is the sgmi- 
next-trouble-spot command, which you invoke by press- 
ing c-c c-o or by selecting Next Trouble Spot from the Move 
menu. While PSGML is not a full validating parser (and it can 
call one easily enough, as we'll see in "Finding Tagging Mis- 
takes") it can locate many potential problems, and the parsing 
that it performs while looking lets it do this visual formatting. 

The most common problem that sgmi-next-troubie- 
spot finds is a tag that doesn't belong somewhere, either 
because it's in the wrong place or because it's not even a valid 
tag for that document (for example, if the generic identifier has 
a typo). If it finds no problems, the cursor jumps to the end of 
the document, finishes up any visual formatting, and displays 
the message ok in the minibuffer. 

With a large DTD, this parsing can take a while. You'll see 
messages like "Parsing doctype" and "Garbage collecting" (a 
colorful term for "RAM reorganization") flash by for a while in 
the minibuffer. To speed this process, you can save the DTD in 
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a special compiled version that PSGML loads more quickly by 
entering the command sgmi-save-dtd at the m-x minibuffer 
prompt. PSGML offers to save the compiled version in the same 
directory with the same filename as the document you are edit- 
ing but with an extension of . ced. If you do change the default 
directory or filename at all, you'll have to specify the full path- 
name of the saved one when you want to use it with the com- 
mand sgmi-ioad-dtd. if you let PSGML save the compiled 
one with the default name and directory it can find this com- 
piled version by itself the next time you edit that document. 

SGML Declarations and DTDs 

PSGML doesn't require you to include an SGML declaration 
with your document. In fact, if you do include it, PSGML 
ignores it. It uses the Reference Concrete Syntax but ignores the 
Reference Concrete Syntax's limitation on element type name 
length. 

PSGML must know how to find your document's DTD so 
that it can enforce your document instance's structure. There 
are three ways to tell PSGML how to locate the DTD to use 
with your document: 

• A SYSTEM identifier in the DOCTYPE declaration. 

• A PUBLIC identifier in the DOCTYPE declaration. 

• One of several Emacs variables set by PSGML. 

The first two methods are standardized and are therefore 
used by other SGML applications. For this reason, the beginner 
is best off ignoring the third method. 

The SYSTEM identifier is the simplest method. Within a 
DOCTYPE definition, such as the following, 

<! DOCTYPE chapter SYSTEM "mybook.dtd"> 
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the keyword SYSTEM tells the software "the DTD is in the fol- 
lowing file on this system." Using the above declaration, on 
most systems the software looks in the document file's direc- 
tory. With some systems you can also specify a relative or abso- 
lute pathname with the file; the following shows a DTD 
filename with an absolute filename: 



<!DOCTYPE chapter system "\dev\sgml\dtds\mYbook.dtd"> 



Some SGML software is pickier about the pathname, expect- 
ing UNIX-style forward slashes {"/") instead of backslashes 
("\"), even if running a DOS or Windows system that uses 
backslashes to identify pathname components. PSGML has no 
problem with the DOS style. 

The PUBLIC identifier is popular when using well-known 
DTDs. The DOCTYPE declaration includes a string after the 
word PUBLIC, such as this one for the DocBook DTD: 



<! DOCTYPE chapter PUBLIC "-//Davenport//DTD DocBook V3.0//EN"> 



The SGML application software (in this case, PSGML) still 
needs to know where a copy of this public DTD is, so the most 
common way to tell it is with a catalog file following the format 
defined by SGML Open Technical Resolution 9401:1995. Each 
entry of this file (commonly called catalog) has the keyword 
PUBLIC followed by the string that identifies the DTD and the 
actual filename (and, if necessary, the location) of the system's 
copy of the DTD. The following shows typical catalog entries 
for the DocBook and HTML DTDs: 



PUBLIC "-//Davenport//DTD DocBook V3.0//EN" 

"DOCBOOK. DTD" 
PUBLIC "-//IETF//DTD HTML//EN" 

" \WEBSTUFF XHTML . DTD " 
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Note that the DocBook entry has no pathname, indicating 
that the docbook . dtd file is in the same directory as the cata- 
log file, while the HTML entry includes an absolute pathname. 

Once the SGML application software knows where the cat- 
alog file is, it can look there to see which DTD file to use with 
the DOCTYPE's public declaration. To tell PSGML where to 
find the catalog file, set the environment variable 
SGML_CATALOG_FiLES to the file's fully qualified name (that is, 
the name with its pathname included). If the file is called cat- 
alog and stored in a directory named \dev\sgmi\dtds\ on a 
DOSAA/indows system, the following line tells PSGML where 
to find the catalog: 



set SGML_CATALOG_FILES=\dev\sgml\dtds\catalog 



<TIP> The UNIX syntax for setting the environment variable 
depends on the shell you're using. 



Keep in mind that a DTD itself may contain declarations for 
public entity sets that it uses, and that you may need to tell the 
application software where to find those entity sets. For exam- 
ple, if your DTD includes the following entity declaration to let 
documents use the public ISO character entity set. 



<! ENTITY % ISOchars PUBLIC 

"-//ENTITIES Public ISO Character Entity Declarations//EN" 

"iso-pijblic"> 



then your catalog file needs an entry to indicate that character 
entity set's location. This means adding an entry like this to 
your catalog file: 



PUBLIC "-//ENTITIES Public ISO Character Entity Declarations//EN" "ISOPUB.ENT" 
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Using PSGML 

PSGML makes it easier to edit SGML files by adding com- 
mands to manipulate SGML document instances and by add- 
ing keystrokes and menu choices that invoke most of these 
commands. Even if the version of Emacs and the operating sys- 
tem that you use cannot display fonts, colored text, or menus, 
PSGML's built-in intelligence still offers help to the writer cre- 
ating a document. It reads and understands your DTD and 
automates the chores of ensuring that your document conforms 
to it, letting you concentrate on the content you're creating and 
not on the correctness of the tags that describe your docu- 
ment's structure. 

PSGML Startup Variables 

In the section "Setting Emacs Variables to Control Its Behav- 
ior," we saw that Emacs has variables that you can set in the 
.emacs file to customize its behavior. PSGML adds several 
new ones, and I've found the following Boolean ones most 
valuable when I use PSGML. I set all of them to t in my 
. emacs file with a line like this: 

(setq sgml-omittag-transparent t) 

sgml-omittag-transparent 

When you tell PSGML that you want to insert a 
new element, you can have it list all the allow- 
able element types that you may insert at the cur- 
sor's current position. If sgml-omittag- 
transparent is set to a nil value, PSGML only 
lists element types that can occur inside the ele- 
ment where the cursor is located. If set to a non- 
nil value, PSGML also lists element types that 
can begin after what PSGML calls the "live" ele- 
ment (that is, the element where the cursor is 



47 



SGML CD 



currently located) if the live element doesn't 
need an end-tag. 

For example, if the live element is a para ele- 
ment and the DTD doesn't require para ele- 
ments to have an end-tag, any commands that 
list valid element types to insert at the cursor 
position will list those that may come after a 
para element as well as those that may appear 
within one. 

sgml-balanced-tag-edit 

if this is set to a non-nil value, each time you tell 
PSGML to insert a certain element, it inserts the 
beginning and end-tag for you, putting your cur- 
sor between them. 

sgml-auto-insert-required-elements 

If this is set to a non-nil value, then each time 
you tell PSGML to insert a particular element, it 
also inserts the tags for any required elements 
within that element. For example, when using 
the DocBook DTD, telling PSGML to insert the 
chapter element also inserts the tags for the 
title element at the beginning of the chapter 
and follows it with a comment telling you to 
insert "one of (list of valid element types)" to tell 
you that the title must be followed by at least one 
of the listed element types. 

sgm I -set-face 

if set to a non-nil value, this variable tells PSGML 
to display (if possible on your monitor) tags, con- 
tent, entity references, and comments in different 
fonts or colors. For more on this, see the section 
"Displaying Markup in Different Fonts and Col- 
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sgml-live-element-indicator 

Setting this to a non-nil value tells PSGML to dis- 
play the document type and the live element 
type on the mode line. For example, if your cur- 
sor is on a title element while editing a Doc- 
Book chapter, the mode line might have the 
following message: 

(SGML [chapter/title])) 

This may slow down Emacs a bit, but the sacri- 
fice is often worth it if your document isn't too 
large. 

sgml-indent-step 

This sets PSGML to automatically indent tags as 
you type to give visual clues about element 
structure. With the sgml-indent-step variable 
set to its default value of two, the tags of an ele- 
ment inside another are indented two more 
spaces from the left than the tags of its container 
element. In the following, we see that the title, 
para, and figure elements' tags are all 
indented two more characters than the sect2 
start- and end-tags, and that the figure ele- 
ment's title and graphic subelements are 
indented two more characters than the figure 
start- and end-tags: 

<sect2> 

<title>A Bosom Friend</title> 

<para>We then turned over the book together, and I endeavored to 
explain to him the purpose of the printing, and the meaning of the few 
pictures that were in it.</para> 

<f igure> 

<title>A Sample Figure</title> 

<graphic f ileref="giftest .gif " f ormat="gif "></graphic> 
</ f igure> 

<para>Thus I soon engaged his interest; and from that we went to 
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jabbering the best we could about the various outer sights to be seen 

in this famous town.</para> 

<sect2> 

Too much indenting can push text too far to the 
right side of your screen, so you can turn indent- 
ing off by setting sgmi-indent-step to a value 
of zero in your .emacs file with the following 
line: 

(setq sgml-indent-step 0) ; default value is 2 



Entering PSGML Commands 

As with other Emacs commands, all PSGML commands can 
be entered at the m-x command prompt, most can be entered 
with keystrokes, and many can be entered through menus if 
your version of Emacs supports menus. 

Keystrokes are usually the fastest. Most PSGML keystrokes 
consist of c-c followed by another Control key combination; 
many are the SGML equivalents of regular Emacs commands. 
For example, in regular Emacs, M-f moves the cursor one word 
forward and M-b moves the cursor one word backward. In 
"Moving Your Cursor Around an SGML Instance," we'll see 
that c-M-f and c-M-b move the cursor forward and backward 
one element. (The c-M-f notation can be a bit confusing; think 
of it as Escape followed by ctri+f, not Escape between the 
Ctrl and f, as it's written. Some versions of Emacs let you 
press Alt instead of Escape for metakeys, so that c-M-f could 
be Ctrl+Alt+f .) 

PSGML adds six new menus to the regular Emacs selection: 
SGML, Modify, Move, Markup, View, and DTD. As this section 
covers each PSGML feature, it mentions any menu alternatives 
to commands and keystrokes. 
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Entering Text 

The sgmi-insert-eiement command could be the one 
you use the most when writing with PSGML. When you enter it 
at the command line (or when you select Insert Element from 
the Markup menu, or more likely, when you enter the c-c c-e 
keystroke that invokes it), PSGML prompts you for the name of 
the element type in the minibuffer: 

Element : 

As with other minibuffer prompts, you can use Emacs's com- 
pletion feature, so you only need to type the first few characters 
at this prompt and then press Tab or the space bar to have 
Emacs fill out as much as it can. If more than one valid element 
type name begins with the letters you typed (and note that 
"valid" part — the fact that this command only offers you valid 
element type names to insert makes it very useful), Emacs lists 
them in a new window so that you can choose one. 

After you tell PSGML the element type to insert, if sgmi- 
balanced-tag-edit and sgml-auto-insert-required- 

eiements are set to non-nil values (see "PSGML Startup Vari- 
ables" for more on these) then PSGML inserts the element's 
start-tag, end-tag, and any required subelements. If a certain 
point in the document needs an element from a choice of sev- 
eral types, PSGML inserts an SGML comment that lists your 
choices. Finally, it puts your cursor right after your new ele- 
ment's start-tag (or the first subelement in it that requires text, 
as we'll see in the figure example below) so that you can start 
typing. 

For example, let's say you want to insert a figure into a Doc- 
Book document. First press c-c c-e, which displays the 
prompt Element: in the minibuffer to ask what element type 
to insert. Enter the letters fi and press Tab to see if Emacs 
enters the remaining letters of the word "figure" for you. No 
other DocBook element types begin with the letters "fi," so 
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Emacs doesn't need to open a separate window to ask "which 
element type begins with 'fi'?" and it adds the "gure" for you in 
the minibuffer. 

When you press Enter, PSGML inserts the following text 
and positions your cursor between the title element's start- 
and end-tags: 

<f igure> 

<title></title> 

<! — one of (blockquote informalequation inf oianaltable literallayout pr\ 
ogramlisting screen screenshot graphic synopsis cmdsynopsis funcsynopsis link o\ 
link ulink) — > 
</figure> 

Note how the line after the title tags is a comment telling 
you that you must include one of the listed element types there. 
The comment is too long to fit on a single line, so it wraps onto 
a second and third line on your screen and puts a backslash (\) 
at each wrapping point to show you that the text after each 
slash is a continuation of the current line. Although the line is 
visually wrapped so that you can see the whole thing, the 
backslashes show that it's still technically one line, which 
makes it easier to delete it once you've heeded the comment's 
advice: simply put your cursor at the beginning of the com- 
ment and press c-k to invoke the kill-line command. 

This description might make the process of inserting a fig- 
ure element appear complicated, but let's review it without 
the background information to see how little work there really 
is: 

1 . Press c-c c-e. 

2. Enter f i at the Element : prompt and press Tab. 

3. Press Enter and start typing the text of the figure's title. 

Sometimes you can't start typing right away because the con- 
tent model of your new element offers a choice of subelements 
at the point where you start entering text. For example, you can 
start a DocBook itemizedList (such as a bulleted list) by 
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entering C-c C-e, the letters "it," and pressing Tab and Enter 
to let Emacs enter the rest of the element type name. PSGML 
enters the tags to start the list and a Listitem start-tag for the 
list's first item, but the Listitem can begin with so many differ- 
ent element types that PSGML inserts a 400-character comment 
to tell you about your choices: 

<ItemizedList> 
<ListItein> 

<! — one of (sidebar procedure msgset simpara para formalpara funcsynop\ 
sis cmdsynopsis synopsis graphic screenshot screen programlisting literallayoutX 
inf ormaltable inf ormalequation blockquote variablelist simplelist segmentedlisX 
t orderedlist ItemizedList indexterm highlights table figure example equation e\ 
pigraph comment bridgehead warning tip note important caution authorblurb anchoX 
r abstract) — > 

</ListItem> 
</ItemizedList> 

If you're entering simple text, you'll probably want to enter a 
para ("paragraph") element. 

if para isn't the only valid element type beginning with the 
letter "p," you'll probably have to enter at least "pa" at the 
Element: minibuffer prompt before you press Tab to tell 
Emacs to fill out the rest of the element type name for you. 
Since the element type representing a simple paragraph of text 
is the one you'll probably enter most often into any document, 
it's good to know that the PSGML sgmi-spiit-eiement key- 
stroke lets you do this with even fewer keystrokes than the 
C-c C-e method. 

Splitting the Live Element 

The sgmi-spiit-eiement command, invoked with 
c-c Enter, tells PSGML to split the live element into two at 
the cursor position. If you decide that an existing paragraph 
should actually be two paragraphs, pressing this keystroke with 
your cursor in that paragraph puts an end-tag and start-tag at 
the cursor location and positions your cursor right after the 
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new start-tag. For example, if you want the sentence beginning 
"Go from Corlears Hook" to begin a new para element in 
Fig. 2.13, 



<para>Circunanbulate the city of a dreany Sabbath afternoon. 
from Corlears Hook to Coentles Slip, and from thence, by Uhltehall, 
northuard. Uhat do you see?</para> 



Figure 2.13. Using sgml-split-element to split an existing element 

pressing c-c Enter with your cursor on the "G" in "Go" has 
the result shown in Fig. 2.14. 



%para>Clrcunanbulate the city of a dreamy Sabbath afternoon. </para> 
<para>So 

from Corlears Hook to Coentles Slip, and from thence, by Uhltehall, 
northward. What do gou see?</para> 

Figure 2.14. Result of splitting an element with sgml-split-element 

You might use the Emacs M-q fill-paragraph keystroke to 
adjust those line breaks, but we'll see a better way that takes 
element structure into account in the "Justifying Element Text" 
section. 

With your cursor just before a paragraph end-tag, 
c-c Enter essentially ends the current paragraph and starts a 
new empty one. This is great when entering new text (as 
opposed to editing existing text) because it enters a large 
majority of your first draft tags for you. For example, let's say 
your cursor is right after the question mark in Fig. 2.15. 



<para>Clrcumambulate the city of a dreamy Sabbath afternoon. 
Go from Corlears Hook to Coentles Slip, and from thence, by Uhltehall, 
northward. What do gou see?B/para> 

Figure 2.1 5. Creating a new element with sgml-split-element 
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Press c-c Enter, and PSGML starts a new paragraph after 
that one and puts your cursor between the new paragraph's 
start- and end-tags, so that you can type away without having 
entered any tags, element type names, or other structural infor- 
mation (see Fig. 2.1 6). 



<para>Circunainbulate the city of a dreamy Sabbath afternoon. 
Go from Corlears Hook to Coenties Slip, and fron thence, by Uhitehall, 
northuard. What do you see?</para> 

<para>Q/para> 



Figure 2.1 6. Result of creating a new element with sgml-split- 
element 

So, unless you're writing highly specialized text, over three- 
quarters of the process of writing with Emacs and PSGML con- 
sists of entering your text and pressing c-c Enter every few 
sentences. The keystroke is easy to remember because we 
already saw that most PSGML keystrokes consist of c-c fol- 
lowed by other characters, and this particular key is the sim- 
plest to follow it — in fact, the Enter key is what you'd press at 
the end of a paragraph with nearly any word processor. 

Keep in mind that the sgmi-spiit-eiement keystroke does 
more than just create new paragraphs. One nice trick is press- 
ing c-c Enter a second time to split the live element's parent, 
or pressing it a third time to split the parent's parent. For exam- 
ple, let's say you just finished typing "may be." in Fig. 2.17. 



<sect1> 

<title>Gone Whalln ' </title> 
<sect2> 

<title>Looinings</title> 

<para>Let us scrape the ice fron our frosted feet, and see uhat 
sort of a place this 'Spouter' nay be.Q/para> 
</sect2> 
</sect1> 



Figure 2.17. Before splitting any elements 
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Pressing c-c Enter, as we already saw in this situation, 
starts a new paragraph under the current one, as shown in 
Fig. 2.18. 



Buffeis Files Tools Edit Seaich SGML Modify Move Markup View DTD Help 
<!DOCTVPE chapter public "-//DaMenportZ/DTD DocBook U2.3//EN"> _»_| 
<chapter> "1 
<title>Fish Stories</title> 
<sect1> 

<title>Gone Whalin ' </title> 
<sect2> 

<title>Loonings</tltle> 

<para>Let us scrape the ice from our frosted feet, and see what 
sort of a place this 'Spouter' mail be.</para> 
<para>Q/para> 
</sect2> 
</sect1> 
<sect1> 

<title>The Carpet-Bag</title> 

<para>I stuffed a <emphasis>shirt</emphasis> or two into ny 
old carpet-bag, <emphasis>tucked</emphasis> it under my arm, and 
<emphasis>started</emphasis> for Cape Horn and the Pacific .</para}> 

<para>quitting the good city of old Manhatto, I duly 
arriue in New Bedford .</para> 

<para>It was on a Saturday night in December .</para> 
</sect1> 
</chapter> 



-«»-Enacs: uhalin.sqm (SGML [chapter] Fill)— L1 B— Bll 



Repeat the connand to split the containing sect2 element 



Figure 2.1 8. Splitting the para element 

Note that alter doing this, a minibuffer message tells you 
Repeat the command to split the containing sect2 
element . In other words, because that para element is inside 
a sect2 element, immediately pressing c-c Enter again ends 
the current sect2 element and starts a new one, putting your 
cursor between the para start- and end-tags that begin our new 
sect2 element (see Fig. 2.19). 
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Buffers Files Tools Edit Search SGML Modifv Move Markup View DTD Help 
<rDOCTVPE chapter- public ■■-//Dagenpor-tZ/DTD DocBook U2.3//EN"> 
<chapter> 

<title>Fish Stot-ies</title> 
<sect1> 

<title>Gone Uhalin'</title> 
<sect2> 

<title>Loonings</title> 

<para>Let us scrape the ice fron our frosted feet, and sec uhat 
sort of a place this 'Spouter' nay be.</para> 
</sect2> 
<sect2> 

<para>Q/para> 
</sect2> 
</sect1> 
<sect1> 

<title>The Carpet-Bag</title> 

<para>I stuffed a <emphasis>shirt</enphasis> or tuo into ny 
old carpet-bag, <eniphasls>tucked</emphasis> it under my arn, and 
<eiiiphasis>started</einphasis> for Cape Horn and the Pacific .</para> 

<para>Quitting the good city of old llanhatto, I duly 
arriue in New Bedford .</para> 

<para>It uas on a Saturday night in December X/para) 
</sect1> 
</chapter> 



-»»-Enacs: uhalin.sgn 



(SGML [chapter] f ill) — L12— (til 



Repeat the connand to split the containing sect1 element 



Figure 2.19. Splitting the sect2 element by repeating the C-c Enter 

keystroke 



Remember that this doesn't automatically insert other ele- 
ments that may be necessary — in this case, the new sect2 ele- 
ment lacks its required title element — so you'll have to 
remember the occasional sgmi-next-troubie-spot key- 
stroke (c-c c-o) to check for such oversights. 

Now the minibuffer message tells you Repeat the com- 
mand to split the containing sectl element. So, 
pressing c-c Enter one more time ends the sectl element 
titled "Gone Whalin'" and starts a new sectl, putting a new 
sect2 element inside of the new sectl and a new para inside 
of the new sect2 (see Fig. 2.20). 
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<title>Gone Hhalin ■ </title> 
<sect2> 

<title>Loonings</title> 

<para>Let us scrape the Ice fron our frosted feet, and see what 
sort of a place this 'Spouter' may be.</para> 
</sect2> 
/sect1> 
sect1> 
<sect2> 

<para>Q/para> 
</sect2> 
?/sect1> 



Figure 2.20. Splitting the sect2 element's enclosing sectl 

Because the new secti needs a title, sgmi-next-troubie- 
spot will give you similar error messages about starting a new 
paragraph without including the sectl element's necessary 
title element. 

For a simpler, more typical example, let's say you're finishing 
a paragraph within a list's first item and you want to begin a 
new list item (see Fig. 2.21). 



<itemizedlist> 




<listitem> 




<para>But uhat thinks Lazarus? Can he 


uarm his blue hands by 


holding then up to the grand northern 


lights?B/para> 


</listiteiii> 




</itenizedlist> 





Figure 2.21. Ready to add a new list item 



After typing the question mark following the word "lights," 
press C-c Enter and PSGML puts a new paragraph in that list 
item, as shown in Fig. 2.22. 
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<itenizedlist> 




<listiten> 




<para>But what thinks Lazarus? Can he 


warm his blue hands by 


holding then up to the grand northern 


lights?</para> 


<para>Q/para> 




</listiten> 




</itenizedlist> 





Figure 2.22. Splitting the para element with C-c Enter 



What you really wanted, however, was to start a new list 
Item, not a new paragraph within the current list item. Pressing 
c-c Enter another time creates this new list item because 
listitem is the parent of the para element that you just split. 
It even puts the start- and end-tags for a new para element in 
that list item, with your cursor between these two tags so that 
you can start typing right away (see Fig. 2.23). 



<itemizedlist> 




<listitein> 




<para>But uhat thinks Lazarus? Can he 


warn his blue hands by 


holding then up to the grand northern 


lights?</para> 


</listitera> 




<listiten> 




<para>Q/para> 




</listitera> 




</ltenizedlist> 





Figure 2.23. Splitting the listitem element by pressing C-c Enter a 
second time 

To review these steps without all the commentary (and to 
show how few steps it really was): you finished a list item, 
pressed c-c Enter twice, and were ready to start typing the 
text of the new list item. 

Inserting Tags Around Existing Text 

So far, inserting elements has meant telling PSGML to insert 
a start- and end-tag pair and to position the cursor between 
them. This is convenient when entering new text into a docu- 
ment, but what about adding tags to existing text? For example, 
when putting a pair of emphasis tags around a word in the 
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middle of a sentence? Using the sgmi-tag-region, sgmi- 
insert-tag and sgmi-insert-end-tag commands and key- 
strokes (along with the convenience of Emacs's completion 
feature) makes this simple. 

The sgmi-tag-region keystroke (c-c c-r) and the Tag 
Region choice of the Markup menu tell PSGML to put a start- 
tag at the beginning of the region and the corresponding end- 
tag at the end. (Remember, the "region" is like a marked block 
in other word processors and text editors, delimited by your 
last marked point and the cursor's current location.) For exam- 
ple, let's say you put your cursor on the "R" in "Right" in Fig. 
2.24, pressed c-space to set the mark there, and moved your 
cursor to the comma after "Whalemen." 



<para>South-eastward fron the Cape, off the distant Crozetts, a 
good cruising ground for Right UhalemenH a sail loomed ahead, the 
Goneg (Albatross) bg name ■</para> 

Figure 2.24. Just before adding emphasis tags 

Pressing c-c c-r displays the prompt Tag region with 
element: in the minibuffer, waiting for you to enter an ele- 
ment type name. You can use completion, so to put emphasis 
tags around the phrase (when using the DocBook DTD) you 
only need to type "em" followed by a Tab to have PSGML fill 
in the "phasis" and then Enter to complete the command, as 
shown in Fig. 2.25. 



<para>South-eastuard fron the Cape, off the distant Crozetts, a 
good cruising ground for <enphasis>Right UhaleinenQ/emphasis> , a sail looned 
ead, the 

Goneg (Albatross) bg nane.</para> 

Figure 2.25. emphasis tags added with C-c C-r 

(The paragraph may look like it needs the fill-paragraph 
keystroke (M-q), but we'll see an even better PSGML version of 
this command in the "Justifying Element Text" section.) Some 
versions of Emacs don't highlight the marked region, so it's 
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easy to forget where you set the last mark, and sometimes the 
sgmi-tag-region command puts the Start- or end-tag where 
you didn't expect it to. To make sure of the mark's location, the 
exchange-point-and-mark keystroke (c-x c-x) mentioned 
earlier is a great way to quickly check. Press it twice (in other 
words, press c-x four times) to check the mark's location and 
then return the cursor to its original position. 

The sgml-insert-tag and sgml-insert-end-tag com- 
mands let you insert start and end-tags individually, c-c < (and 
Insert Start-Tag from the SGML menu) invoke the sgml- 
insert-tag command, and C-c / (and Insert End-Tag from 
the same menu) invoke the sgml-insert-end-tag com- 
mand. To put emphasis tags around the word "No" in 
Fig. 2.26, first put your cursor at the "N." 



<para>Unconsciously clapping the uinegar-cruet to one side of 
her nose, she i-uninated for an instant; then exclaimed — '[Jo? I hauen't 
seen it since 1 put it there .' </para> 



Figure 2.26. Before inserting emphasis start-tag 

Press c-<. At the Tag: < prompt, you only need to enter 
"em" when using the DocBook DTD and then Tab to complete 
the element name. Press Enter to insert the start-tag as shown 
in Fig. 2.27. 



<para>Unconsciously clapping the winegar-cruet to one side of 
her nose, she ruminated for an instant; then exclaimed — ' <emphasis>|Io? I hauen'\ 
t 

seen it since I put it there .' </para> 



Figure 2.27. emphasis start-tag inserted with C-< 

Entering the emphasis end-tag requires even less typing 
because it's the only end-tag that can appear right after an 
emphasis Start-tag. With your cursor on the exclamation point, 
press c-c /, and that's it — you don't even have to press Enter. 
PSGML enters the emphasis end-tag for you. 
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Inserting Elements with the Menu 

If your copy of Emacs has a menu, selecting Insert Element 
from the Markup menu displays a new menu under the menu 
bar's Markup choice with a list of element types that are valid 
at the cursor's current position. If only one element type is 
valid, only one shows up there; if there are too many valid 
choices to vertically fit on the screen, PSGML replaces the 
Markup menu with a menu offering multiple submenus of the 
valid element types. For example, with your cursor right after a 
DocBook para element, selecting Insert Element from the 
Markup menu displays the element type menus shown in 
Fig. 2.28. 



Buffers Files Tools Edit Searc h SGML Modify Moue Markup Uiei; DTD Help 

Element ' abstract fornalpar' abstract 



uut^iYrt. cnapter puDlxc 
<*ENTITV y. localnods SYSTEM 

xlocalnods; 
1> 



loby? 




Element ' f uncsynop' -' note' 
Element ' orderedli' -' toe' 
Element ' variablel' -' uarnxn 



he Carpet -Ba^^^^^^^^ ^^^^^^^^^ 
[T stuffed a TSAff^^^^E^iirt^^^^^^^^H or two into m 

jld carpet -bafl, jl^phas is >t uc ke dB^^^^^^^Bitun de r Piy arm 
tartedHamiha&i^j for Cape Horn and the Pacific.| 

luitting the goo^city of old Manhatto, I duly 

arri ue in New Bedford. tf^^^H 

lit was on a Saturday night in December.^^^^^l 



>■ anchor 

authorblurb 
h_ be gin page 
bibliography 
blockquote 
bridgehead 
caut ion 
cmdsynops is 
code 
comment 
epigraph 
equat ion 
example 
f igure 
f ormalpara 



«oading cl-extra — done 



Figure 2.28. First of four menus of DocBook elements that can follow a 
para element 



To insert individual start- or end-tags, select Insert Start-Tag 
or Insert End-Tag from the same menu. 



Justifying Element Text 

We saw that M-q (fill-paragraph) justifies a paragraph in 
Emacs, redistributing words in the paragraph to adjust the line 
lengths to just under the right margin setting. An SGML docu- 
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ment instance may have text — whether data, tags, or some 
combination — on every line, so pressing M-q would combine a 
lot of text into a huge paragraph. 

Instead, use the sgmi-f ill-element command, available 
by pressing C-c C-q or by selecting Fill Element from the Mod- 
ify menu. In technical terms, it fills the biggest enclosing 
mixed-content element or fills the subelements if the enclosing 
element only has element content. In layman's terms, the first 
part of this tells us that PSGML doesn't justify the text of an ele- 
ment that only has data (such as emphasis in the example 
below). Instead, it justifies the container element in which 
those elements occur alongside other data. 

<sectl> 

<title>The Chase — Third Day</title> 

<para>But aye, old mast, we both grow old together; sound in our 
hulls, though, are we not, my ship? Aye, minus a leg, that's all. By 
heaven this dead wood has the better of my live flesh every 
way.</para> 

<para>I can't compare with it; and I've known some ships made of 
dead trees outlast the lives of men made of the most vital stuff of 
vital fathers. <emphasis>What' s that he said?</emphasis> he should still go bef\ 
ore me, my pilot; and yet to be 

seen again? But where? Will I have eyes at the bottom of the sea, 
supposing I descend those endless stairs and all night I've been 
sailing from him, wherever he did sink to.</para> 
</sectl> 

In the above example, I just added the emphasized phrase 
"What's that he said?," which obviously threw off the para- 
graph's line breaks. Whether my cursor is on the word "said" 
between the emphasis tag pair or on the word "fathers" to the 
left of the emphasis Start-tag, pressing C-c C-q justifies the 
paragraph to look like this: 

<sectl> 

<title>The Chase — Third Day</title> 

<para>But aye, old mast, we both grow old together; sound in our 
hulls, though, are we not, my ship? Aye, minus a leg, that's all. By 
heaven this dead wood has the better of my live flesh every 
way . </para> 



63 



SGML CD 



<para>I can't compare with it; and I've known some ships made of 
dead trees outlast the lives of men made of the most vital stuff of 
vital fathers. <emphasis>What' s that he said?</emphasis> he should 
still go before me, my pilot; and yet to be seen again? But where? 
Will I have eyes at the bottom of the sea, supposing I descend those 
endless stairs and all night I've been sailing from him, wherever he 
did sink to.</para> 
</sectl> 

If I had pressed the regular Emacs fill-paragraph key- 
stroke (M-q), It would have combined that paragraph with the 
paragraph before it and any other text after the most recently 
skipped line and before the next one. 

According to the second part of the sgmi-f ill-element 
command's technical description in the PSGML Info file, if the 
cursor is in an element that only has element content, with no 
data other than those in its subelements, then PSGML rejusti- 
fies all of that element's subelements. In the last example, if the 
cursor had been right after the secti start-tag, pressing 
c-c c-q would have also justified the paragraph with the 
emphasis element, along with the other secti subelements. 

With your cursor at the beginning of a document, this tech- 
nique is a handy way to clean up an entire document before 
saving it. 

Indenting Text 

We saw in the "PSGML Startup Variables" section that the 
. emacs file's sgmi-indent-step variable makes it possible to 
have PSGML automatically indent document tags as you type 
in order to give visual clues about the structure of the docu- 
ment instance. Just as edits to existing text can throw off the 
justification so that you need sgmi-f ill-element to line it up 
again, the indenting can get mangled by edits as well, and 
there's a command to fix it: indent-region. Being a regular 
Emacs command (as opposed to a special PSGML command) 
the M-c-\ keystroke that invokes this doesn't begin with a c-c. 
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It indents according to SGML element structure because it fol- 
lows the rules set by the current mode, which in this case is 
PSGML. 

For example, the following text, after some edits, has hap- 
hazard indentation: 

<sect2> 

<title>A Bosom Friend</title> 

<para>We then turned over the book together, and I endeavored to 
explain to him the puirpose of the printing, and the meaning of the few 
pictures that were in it.</para> 
<f igure> 
<title>A Sample Figure</title> 

<graphic fileref="giftest .gif " f ormat="gif "></graphic> 
</figure> 

<para>Thus I soon engaged his interest; and from that we went to 
jabbering the best we could about the various outer sights to be seen 
in this famous town.</para> 

After we mark it as a region and press m-c-\, PSGML re- 
indents it to make the element structure much clearer: 

<sect2> 

<title>A Bosom Friend</title> 

<para>We then turned over the book together, and I endeavored to 
explain to him the purpose of the printing, and the meaning of the few 
pictures that were in it.</para> 

<f igure> 

<title>A Sample Figure</title> 

<graphic f ileref="gif test. gif " format="gif "></graphic> 
</figure> 

<para>Thus I soon engaged his interest; and from that we went to 
jabbering the best we could about the various outer sights to be seen 
in this famous town.</para> 



Moving Your Cursor Around an SGML Instance 

In the section "Moving Your Cursor Around," we saw how to 
move your cursor one character or word to the left or right, one 
line up or down, and to the beginning or end of a line or docu- 
ment. PSGML takes advantage of an SGML document's struc- 
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ture to provide several handy new cursor movement 
commands. Essentially, these keystrokes let you quickly put 
your cursor where you want without the tags getting in your 
way. 

To more easily remember PSGML cursor movement key- 
strokes, keep in mind that many are the SGML equivalents of 
similar Emacs commands, entered by preceding the same key- 
stroke with the Escape key. (Remember that the Emacs docu- 
mentation convention represents a combination like Escape 
followed by ctri+A as c-M-a, with the "M" indicating the 
Escape key.) 

The Emacs keystrokes that move the cursor to the beginning 
and end of the current line are C-a and C-e, respectively. The 
PSGML keystroke to move the cursor to the beginning of the 
live element is c-M-a, (sgml-beginning-of-element) which 
moves it to the first data character of the current element. 
C-M-e (sgml-end-of-element) moves to the end of the live 
element, putting the cursor at the "<" that begins the element's 
end-tag so that you can add new text to the end of that ele- 
ment. (Selecting Beginning of element or End of element from 
the Move menu also executes these commands.) 

For example, with your cursor on the "\" in "shirt" in Fig. 
2.29, pressing c-M-a moves it to the "s" in the same word. 
C-M-e moves it right after the "t" that ends the word, because 
the entire emphasis element consists of the word "shirt." With 
your cursor on the word "two" following "shirt," c-M-a moves 
it to the "1" that starts the first sentence, and c-M-e moves it 
right after the period following the word "Pacific" because that 
para element is the new live element once your cursor is out- 
side of that emphasis element. 

Pressing either of these keystrokes a second time won't have 
any effect, just as pressing c-a when your cursor is already at 
the beginning of a line won't move your cursor anywhere. 
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<sect1> 

<title>The Carpet-Bag</title> 

<para>I stuffed a <emphasis>shQrt</emphasis> or two into my 
old carpet-bag, <erophasis>tucked</enphasis> It under my arm, and 
lCenphasis>started</einphasis> for Cape Horn and the Pacific .</para> 

<para>quitting the good city of old Manhatto, I duly 
arriue in New Bedford .</para> 

<para>It was on a Saturday night in Decembei' .</para> 
</sect1 > 



Figure 2.29. Moving your cursor around 

To jump forward or backward an element, use the c-M-f 
(sgml-f orward-element) and C-M-b (sgml-backward-ele- 
ment) keystrokes, or select Forward element or Backward ele- 
ment from the Move menu, sgml-f orward-element moves 
to the point right after the live element's next subelement; for 
example, with your cursor on the word "stuffed" in Fig. 2.29, 
C-M-f jumps it to the space just before the word "or." Pressing 
it a second and third time moves your cursor to the space 
before the words "it" and "for" respectively, but pressing it a 
fourth time displays the message "No more elements in para 
element" in the minibuffer. Your cursor is still in the para ele- 
ment, but there are no more elements within it after the word 
"for." 

For the same reason, putting your cursor on the word "shirt" 
and pressing c-M-f displays the message "No more elements 
in emphasis element" because there are no elements within 
that emphasis element to jump past. 

sgmi -backward-element behaves similarly in the opposite 
direction. With your cursor on the word "it" in Fig. 2.29's first 
para element, pressing c-M-b jumps it to the < of the empha- 
sis start-tag following "carpet-bag, " and repeating the key- 
stroke moves the cursor to the emphasis start-tag after the 
phrase "stuffed a " near the beginning of the paragraph. Press- 
ing it a third time displays an error message similar to the one 
we saw when we tried to jump the cursor forward in an ele- 
ment with no more contained elements, but this time no con- 
tained elements precede the cursor: "No previous element in 
para element." 
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sgml-f orward-element and sgml -backward-element 
demonstrate PSGML's intelligence because they show that 
PSGML knows your document is not just a bunch of text with 
tags mixed in but rather an organized document with elements 
inside of other elements in a specific structure. Three other 
commands that take advantage of your document's structure to 
help you navigate it are sgml-down-element, sgml-up-ele- 
ment, and sgml-up-backward-element. (in addition to the 
keystrokes described below, these are available as Up element 
Down element, and Backward up element on the Move 
menu.) 

It's easy to think of "up" and "down" as moving up and 
down on your screen, but that's what the "forward" and "back- 
ward" commands do. These "up" and "down" commands 
move up and down in your element hierarchy, moving up to an 
element's container element or down into one of its contained 
elements. 

For example, with your cursor after the title end-tag in 
Fig. 2.29, your cursor is in the secti element but not in any of 
its contained elements. Pressing c-M-d for the sgmi-down- 
eiement command jumps your cursor to the beginning of the 
first element in sectl after the cursor's current position: the "I" 
beginning the "I stuffed a" phrase. Pressing c-M-d again moves 
it to the beginning of the first element inside of that para ele- 
ment: the "s" in the emphasis element's "shirt." Pressing it 
again displays an error message in the minibuffer because this 
emphasis element only has data, with no subelements. 

When moving up the element hierarchy, you have a choice 
of moving your cursor forward or backward to a point in the 
live element's parent element. Starting at the emphasis ele- 
ment with the word "shirt," the next element up the hierarchy 
is a para, SO pressing C-c C-n for the sgml-up-element 
command jumps the cursor to a position in that para element 
right after the emphasis element just before the word "or." 
Pressing C-c C-n again moves it one level up from that para 
element to a point after the para end-tag following the words 
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"Cape Horn and the Pacific." (Again, don't forget the up/down 
forward/backward distinction, or this command may seem 
counter-intuitive because your cursor goes down the screen as 
you move up the document hierarchy.) At this point, the lowest 
level element containing the cursor's position is a secti, so 
you've moved the cursor up from an emphasis element to a 
para element to a secti element. 

To move up the hierarchy to an earlier point in the parent 
element instead of a later point, press c-m-u for the sgmi- 
backward-up-element command. With your cursor on the 
word "shirt" in Fig 2.29's first emphasis element, this puts your 
cursor after the words "stuffed a " at the "<" that begins that 
emphasis element's start-tag. Now it's in a para element; 
pressing this keystroke again moves the cursor to the "<" of the 
para element's start-tag preceding the "I stuffed a" sentence. 
Repeating this keystroke moves it to the beginning of the secti 
start-tag, the chapter start-tag, and so on up to the beginning 
of your document element. 

Another great way to quickly put your cursor where you 
want it is the sgmi-next-data-f ieid keystroke (c-c c-d). It 
jumps your cursor to the next valid place for character data, 
regardless of the structural relationship of the tags around the 
cursor. For example, whether your cursor is on or before the 
secti or title start tags in Fig. 2.30, pressing c-c C-d moves 
it to the "T" beginning the phrase "The Carpet-Bag." Pressing it 
again jumps to the "I" in "I stuffed," then the "s" in shirt, and 
then the space before the word "or." Selecting Next Data Field 
from the Move menu also executes this command, although 
you'll use sgmi-next-data-fieid often enough that the key- 
stroke is more efficient. 



<seHtl> 

<titLe>The Carpet-Bag</title> 

<pai-a>I stuffed a <enphasis>shii-t</enphasis> or tuo into ny 
old cai-pet-bag, <enphasis>tucl<ed</eiiiphasis> it under ny arn, and 
|||enphasis>started</enphasis> for Cape Horn and the Pacific .</para> 



Figure 2.30. Using sgml-next-data-f ield 
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After it inserts the tags, the sgmi-insert-eiement key- 
stroke (c-c C-e) usually puts your cursor right where you want 
to start typing, but sometimes you find your cursor surrounded 
by tags representing enough elements within elements that the 
best place for your cursor isn't immediately obvious. (This is, 
after all, SGML.) When you finish inserting and arranging the 
tags that show part of a document's structure, c-c c-d is often 
the quickest way to go back to typing your document's data 
content. 

Deleting, Moving, and Copying Elements 

We already saw that the Emacs kill-region keystroke 
(c-w), like the "cut" command in other text editors and word 
processors, deletes the marked area (or, in Emacs talk, the 
"region") from your document and stores it in a temporary 
buffer, available for pasting ("yanking") to a new location with 
the c-y keystroke if you plan to move the text instead of delet- 
ing it. 

To kill an SGML element, you could move the cursor to the 
element's beginning, set the mark there, move to the end, and 
press c-w, but PSGML gives you the sgmi-kiii-eiement key- 
stroke (c-M-k) (and the Kill Element choice of the Modify 
menu) to automate this. It kills the text from the cursor's current 
location to the end of the next element contained by the live 
element. 

Because it also deletes any text from the cursor to the start of 
the element you meant to delete, be careful where you put 
your cursor before you press c-M-k. (And, remember the C-_ 
keystroke to undo mistakes when you use the commands 
described in this section.) For example, with your cursor on the 
"n" of the word "native" in Fig. 2.31, pressing c-M-k deletes 
the phrase "native of <emphasis>Kokovoko</emphasis>" 
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<sect1> 

<title>Biographical</title> 

<para>queequeg was a Qatiue of <einphasis>Kokouoko</eiiiphasis>, an 

Island far auaij to the West and South .</para> 

<para>It is not damn in any map; true places neuer are.K/paraf 
</sect1> 
<sect1> 

<title>Wheelbarrow</title> 

<para>Next morning, Monday, after disposing of the embalmed head 
to a barber, for a block, I settled my own and comrade's bill; 
using houeuer, my comrade's money .</para> 
</sect1> 



Figure 2.31. Using sgml-kill-element 

As with the sgml-forward-element keystroke (C-M-f), 
killing the next subelement with c-M-k displays an error mes- 
sage in the minibuffer if there is no next subelement. For exam- 
ple, pressing it with your cursor on the word "island" in the last 
example displays the message "No more elements in para ele- 
ment" because the cursor is in a para that has no subelements 
after the cursor's position. In fact, "sgml-kill-next-subelement" 
might have been a better name for the c-M-k keystroke's com- 
mand, but that's a bit long. 

sgml-kill-element is handy for moving elements because 
it treats the entire element as a structural unit that includes its 
subelements. If you move an element that has subelements 
which in turn have subelements, sgml-kill-element kills 
them all into the kill buffer. In Fig. 2.31, with your cursor just 
before the secti start-tag preceding the "Biographical" title, 
pressing c-M-k grabs everything down to the secti end-tag 
after the phrase "true places never are," with the result shown 
in Fig. 2.32. 



<sect1> 

<title>Wheelbarrou</title> 

<para>Next morning, Monday, after disposing of the embalmed head 
to a barber, for a block, I settled my oun and comrade's bill; 
using houeuer, my comrade's money .</para> 



Figure 2.32. After killing the first secti element 
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Moving the cursor after the remaining secti end-tag and 
pressing the Emacs yank keystroke (c-y) copies the recently 
killed secti element titled "Biographical" and all of its subele- 
ment from the kill buffer to the cursor's position. This moves it 
after the secti element that it used to precede (see Fig. 2.33). 



<sect1> 

<title>Wheelbai-row</title> 

<para>Next morning, Monday, after disposing of the embalned head 

to a barber, for a block, I settled ny oun and comrade's bill; 

using houeuer, my comrade's money .</para> 
</sect1> 
<sect1> 

<title>Biographical</title> 

<para>Queequeg uas a natiue of <emphasis>Kakouoka</emphasis> , an 
island far away to the Uest and South .</para> 
<para>It is not doun in any map; true places newer are.</para> 
^sect1>| 



Figure 2.33. First secti element yanked to a new location 

Before we move on to copying elements, two other PSGML 
deletion commands are worth mentioning. They don't delete 
entire elements, but both speed up common operations 
enough to come in handy. 

The sgmi-untag-eiement keystroke (c-c -) removes the 
start- and end-tags from the live element. With your cursor on 
the word "Queequeg" in Fig. 2.33, C-c - would remove the 
para Start- and end-tags; with your cursor just before that para 
start-tag, it would remove the secti start- and end-tags. Select- 
ing Untag Element from the Modify menu also performs this 
command. 

This command's greatest value is in removing tags around in- 
line elements (that is, elements in mixed content). For example, 
if you decide that the word "Kokovoko" in that example 
shouldn't be emphasized, putting your cursor anywhere on that 
word and pressing this keystroke removes the emphasis start- 
and end-tags. 

The sgmi-kiii-markup keystroke (c-c c-k) and the Kill 
Markup choice of the Modify menu kill anything between the 
"<" at the cursor and its matching ">" character. This includes 
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markup declarations (such as comments and marked section 
delimiters), tags, and processing instructions. This command is 
great for deleting the comments that PSGML inserts to give you 
hints about necessary elements when you have sgmi-auto- 

insert-required-elements set tO a non-nil value, because 
after you've followed the comment's advice, it only clutters up 
your document. 

PSGML has no built-in command to delete from the cursor 
position to the end of the current element, so I wrote a macro 
to do this for my .emacs file. It didn't work, so I'd like to thank 
Lennart Staflin, PSGML's author, for straightening it out for me. 
Once you add the following to your .emacs file, pressing 
c-c k calls the macro. 

(defun sgml-kill-to-eoelement () ; kill to end of element 
(interactive) 
(let ((start (point))) 

( sgml-end-of-element ) 
(kill-region start (point)))) 

; assign to ^Ck keystrokes 

(define-key global-map "^Ck" 'sgml-kill-to-eoelement) 

Copying Elements 

To copy an element with all of its subelements, you have two 
options. First, you could delete it using any of the keystroke 
sequences just described, immediately paste it back at the cur- 
sor's position, and then paste it to any place where you want a 
new copy. 

Or, to copy it to the kill buffer without deleting it, you can 
perform the following steps: 
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1 . Press the sgml-backward-up-element keystroke 
(c-M-u) to move your cursor to the beginning of the ele- 
ment's start-tag. If the cursor is in a subelement of the ele- 
ment that you intend to copy, you may need to press this 
more than once to put the cursor where you want it. 

2. Press c-@ or c-space to mark that point as the beginning 
of a region to copy. 

3. Press the sgmi-f orward-eiement keystroke (c-M-f) to 
move your cursor after the element's end-tag. 

4. Press the regular Emacs kill-ring-save keystroke (m-w) 
to copy that element into the kill ring. 

To summarize: c-m-u, c-@, c-M-f, and m-w. Once you get 
used to this, you'll find it much quicker than the "manual" way 
to copy an element into a kill ring or word processor clipboard, 
where you would enter a command to search backward, find 
the start-tag, mark that point as the beginning of the block to 
copy, enter the command to search for the end-tag, and then 
copy the region to the clipboard or kill ring. 

To copy an element into the kill ring even more quickly, add 
the following macro and key definition to your .emacs file and 
press c-c w to copy the current element: 

(defun sgml-copy-element () 
(interactive) 

( sgml-backward-up-element ) 
(let ((start (point))) 

(sgml-f orward-eiement ) 
(kill-ring-save start (point) ) ) ) 

; assign to ^Cw keystroke 

(define-key global-map '"^Cw" 'sgml-copy-element) 

(I'd like to thank Lennart Staflin for helping me with this 
macro as well.) 
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Editing Attributes 

Including the PSGML menus, there are four ways to edit an 
element's attribute values. The first is to simply move your cur- 
sor to the element's start-tag and type in the attribute name and 
value. For example, to add an href value so that the a element 
in Fig. 2.34 links to a Nantucket web site, 



<p>Nou, the Pequod had sailed from <aQMantucket</a> at the 
uery beginning of the Season-on-the-Line . </p> 



Figure 2.34. Adding an attribute value by typing it 

you could move your cursor to the ">" in the start-tag and just 
type in the attribute and value as shown in Fig. 2.35. 



<p>Now, the Pequod had sailed fron <a href ="http ://www.nantucket .con">Nantucket\ 
</a> at the 

very beginning of the Season-on-the-Line .</p> 



Figure 2.35. Entered attribute value 

This is no fun, and could be done with any text editor. The 
other methods for editing attribute values take advantage of 
PSGML features that make this easier. 

The PSGML sgml-insert-attribute keystroke (C-c +) 
and the Insert Attribute choice of the Markup menu are more 
versatile than their names suggest because they also let you 
edit existing attribute values. With your cursor on the start-tag, 
end-tag, or data content of an element, pressing this keystroke 
displays the prompt Attribute name: in the minibuffer. You 
can take advantage of Emacs's completion feature, so you only 
need to type the first few characters and then press Tab or 
space to finish the attribute name. If you press one of these 
keys without specifying enough letters to indicate which 
attribute value to edit, PSGML displays the possibilities in a 
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separate window. For example, if you press Tab without first 
typing any letters of the a element's attribute names, you'll see 
the attribute name list shown in Fig. 2.36. 



Buffers Files Tools Edil Search Minrbuf Help 

<p>Moii, the Pequod had sailed fi on <a href ="http ://www.nantucket .com"> 
Nantucl<et</a> at the uery beginning nf the Season-on-the-Line .</p> 
<p>I can't compare uith It; and I'ue knoun some ships made of dead 
trees outlast the liues of men made of the most uital stuff of uital 
fathers. Ifhat's that he said? he should still go before me, my pilot; 
and yet to be seen again? But uhere? Will I have eyes at the bottom 
of the sea, supposing I descend those endless stairs and all night 
I'ue been sailing from hin, uherever he did sink to.</p> 



i 



Emacs: uhalin.htm 



(SGML [htnll Fill) — L11— 21% 



Click mouse-2 on a completion to select it. 

In this buffer, type RET to select the completion near point. 



Possible completions arc: 

href 

name 

reu 

urn 



3511! 

Attribute name: 



methods 

rel 

title 



Figure 2.36. Listing the a element's attributes with the sgml-insert- 
attribute command 



After you enter the attribute name and press Enter, the 
minibuffer displays the attribute's declared value (data type) 
and current specified value (if any) and asks you to enter the 
new value as shown in Fig. 2.37. 
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Buffers Files Tools Edit Seaich Minibuf Help 

<p>f4oi>i, the Pequod tiad sailed fron <a href ="http ://www.nantucl<et .com"> 
Nantucl<et</a> at the wery beginning of the Season-on-the-Line .</p> 
<p>I can't compare uith it; and I'ue knoun some ships made of dead 
trees outlast the liues of men nade of the nost vital stuff of uital 
fathers. Uhat's that he said? he should still go before ne, my pilot; 
and yet to be seen again? But uhere? Will I haue eyes at the bottom 
of the sea, supposing I descend those endless stairs and all night 
I'ue been sailing from bin, uhereuer he did sink to.</p> 



</body> 
</htnl> 



Emacs: uhalin.htm 



(SGML [html] fill)— L11— Bot 



Ualue for href (cdata Default: http://wuw.nantucket.com): 



Figure 2.37. The sgml-insert-attribute command's prompt for a 
new href value 



You don't need to enter quotes around the value; PSGML 
adds them for you in the document instance. Responding to the 
prompt above with http://www.nantucket.gov, as shown 
in Fig. 2.38, 
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Buffers Files Tools Edit Seaich Minibuf Help 

<p>Noiii, ttie Pequod tiad sailed fron <a href="http://»iww. nantucket.com"> 
Nantucket</a> at the uery beginning of ttie Season-on-the-Line .</p> 
<p>I can't compare uitti it; and I'ue knoun some ships made of dead 
trees outlast the liues of men made of the nost uital stuff of uital 
fathers. Ifhat's that he said? he should still go before me, my pilot; 
and yet to be seen again? But where? Will I have eyes at the bottom 
of the sea, supposing I descend those endless stairs and all night 
I'ue been sailing from hln, uhereuer he did sink to.</p> 



</body> 
</htnl> 



Emacs: uhalin.htm 



(SGML [htnl] Fill) — L11— Bot 



Ualue for href (cdata Default: http://www.nantucket.com): http://www.nantucket.goul 



Figure 2.38. Entering a new href value 



and pressing Enter changes the markup to that shown in 
Fig. 2.39. 



<p>Now, the Pequod had sailed from <a href ="http ://www.nantucket .gou"B</a> at 
the wery beginning of the Season-on-the-Line. </p> 



Figure 2.39. Result of editing the attribute value 

You can even use completion to enter the attribute's value, if 
the declared value is a name token group. For example, the 
HTML DTD's IMG element defines its align attribute with this 
line: 

ALIGN (top I middle I bottom) # IMPLIED 

When editing an img element's align attribute, after you 
press c-c + and enter align as the attribute name, pressing 
either t, m, or b (for "top," "middle," or "bottom") and then Tab 
enters the complete attribute value for you. 
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An even easier way to edit attributes, especially when edit- 
ing more than one from the same element, is by using the 
sgmi-edit-attributes keystroke (c-c c-a) or by selecting 
Edit Attributes from the Modify menu. This splits the screen to 
display a new window, showing the live element's attributes 
listed on a form that you fill out. (As with sgmi-insert-eie- 
ment, your cursor can be on the element's start-tag, end-tag, or 
data content when you invoke this command.) Pressing 
c-c c-a with your cursor on the "Nantucket" text displays the 
split screen shown in Fig. 2.40. 



emacs.exe 



Buffers Files Tools Edit Seaicfi ffelp 

<p>Noiii, the Pequod had sailed from <a href ="http ://uui«.nantucl<et .gov"> 
Nantucket</a> at the wery beginning of the Season-on-the-Line .</p> 
<p>I can't compare uith it; and I'ue knoun some ships made of dead 
trees outlast the liues of men made of the most uital stuff of uital 
fathers. Uhat's that he said? he should still go before me, my pilot; 
and yet to be seen again? But where? Will I haye eyes at the bottom 
of the sea, supposing I descend those endless stairs and all night 
I'ue been sailing from hin, uhereuer he did sink to.</p> 



-««-Emacs: whalin.htm (SGML [html] Fill) — L10— 21% 



<a — Edit ualues and finish vjith C-c C-c -- 
href = [Jttp ://www.nantucket .gou 

— cdata: ttlMPLIED — 
name = UDEfftULT 

— cdata: ttlMPLIED — 
rel = ItDEFftULT 

— name: ttlMPLIED — 
rev = 8PEFBULT 

— name: ttlMPLIED — 
urn = ttPEFftULT 

— cdata: ttlMPLIED -- 

BiBj„uj.i»ij m 1 1 1 n |i| 1 1 1 ^finirrr"»"»<!fflra*™*™B 

Mark set 



Figure 2.40. Entering attribute values with the sgml-edit- 
attributes "form" 

Move your cursor to any attribute value and enter the new 
value. All your cursor keys work here, and the Tab key pro- 
vides a shortcut for jumping from one field to the next. 



I 
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As the window tells you, pressing c-c c-c indicates that 
you are finished inserting your new values into the document 
markup and closes the new window. To abort the attribute win- 
dow, the usual Emacs deiete-window keystroke (c-x 0) 
closes that window and ignores any changes made there. 

Completion doesn't work when entering attribute values, but 
you don't really need it because the attribute editing window 
lists the possibilities for any element whose valid choices are 
listed in the attribute definition. For example. Fig. 2.41 shows 
the attribute editing window for an HTML img element; note 
the "bottom middle top" list on the second line of the align 
entry: 



Buffers Files Tools Edit Seaicli hielp 
<p>Nou, the Pequod had sailed from <a> 

Nantucket</a> at the uery beginning of the Season-on-the-Line .</p> 
<p>I can't compare uith it; and I'ue knoun some ships made of dead 
trees outlast the liues of men made of the most uital stuff of uital 
fathers. What's that he said? he should still go before me, my pilot; 
and yet to be seen again? But where? Will I have eyes at the bottom 
of the sea, supposing I descend those endless stairs and all night 
I'ue been sailing from him, whereyer he did sink to.</p> 
<img src="whale .gif "> 



--»»-Emacs: whalin.htn 



(SGML [html] Fill) — L18— 21% 



<img — Edit ualues and finish with C-c C-c 
src = uhale.gif 

— cdata: ItREQUIRED -- 
alt = BPEFflULT 

— cdata: ttlMPLIED — 
align = HiDEFflULT 

— (bottom middle top): ItlMPLIED — 
ismap = ItDEFHULT 

— (ismap): ttlHPLIED — 



MIMj,,UJ.l»iJ,L|J..Ujm,lllJJ..|.l 



ln■^^^l■g!H■jlln^mm^I.»^I^^^^^a 



Figure 2.41. Attribute editing form showing possible img values 



The fourth and easiest way to edit attribute values is by 
selecting Insert Attribute from the Markup menu if menus are 
available. Don't be misled by its name — like the sgmi- 
insert-attribute command automated by the c-c + key- 
stroke, this menu choice lets you edit existing attribute values 



80 



Editing SGML Documents with the Emacs Text Editor 



as easily as inserting new ones, it displays a menu of the live 
element's attributes, and selecting any of those attributes dis- 
plays the available choices. If the attribute's declared value is a 
named token group, PSGML displays each of the choices as a 
choice on this menu so that you merely need to click the value 
to insert it into the document instance markup (see Fig. 2.42). 



Buffers Files Tools Edit Search SGML Modify Moue Markup Uieu DTD Hel 

src 
alt 

alignh botton 
isnap^^ niddle 
top 



trees outlast the Ixues of nen made of the nost i 
fatliers- Uhat's that he said? he should still go 
and yet to be seen again? But where? Uill I havi 
□f the sea, supposing I descend those endless staiL 
^^^^^^^^^^^^^gn hin, wherever he did sink to 



t of vxtal 
, ny pilo t; 



itnl> 



3,Tr,i!«i»i»mBm 



Figure 2.42. Selecting attribute values from a menu 



Most of these attribute value menus include Set attribute 
value as a choice. Selecting it displays a prompt in the 
minibuffer that waits for you to enter a value. 



Finding Tagging Mistakes 

We saw that, after first displaying a document instance in 
Emacs, the sgmi-next-troubie-spot keystroke (c-c c-o) is 
the quickest way to parse the text to read its tags so that PSGML 
knows the document's structure. For many PSGML users, it's 
the first thing they do when they bring up a document. 

It's handy to repeat this keystroke several times as you edit a 
document, just like saving it. (In fact, doing it just before each 
save helps to ensure that you're saving a structurally sound 
document.) Move your cursor to the top of your document or 
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before your most recently edited block of text and press 
C-c C-o. If your cursor jumps to the bottom and the message 
"Ok" displays in your minibuffer, PSGML found no problems. 

Remember, however, that PSGML is not a full validating 
parser; it just helps you along. To validate properly, the sgmi- 
vaiidate keystroke (C-c c-v) splits your screen into two win- 
dows, runs a parser against your document, and puts error and 
status messages in the new window. The default parser in 
PSGML 0.4 beta 2 is James Clark's free nsgmis parser, which is 
covered in more detail in the "Parsing and Validating SGML 
Documents with nsgmis" chapter; we'll see below how to set 
PSGML to run another parser if you prefer. 

After you press c-c c-v (or select Validate from the SGML 
menu), PSGML first displays the command it's about to run in 
the minibuffer to give you the opportunity of editing it: 

Validate command: nsgmis -s whalin.sgm 

(The s switch tells nsgmis to only show error messages and not 
to show the output of the parse.) The edit you're most likely to 
make is to insert the name of a file with the document's SGML 
declaration before the document's filename, nsgmis, being a 
very thorough validator and parser, cares much more about the 
SGML declaration than PSGML does and assumes the Refer- 
ence Concrete Syntax if it doesn't find one. Because this con- 
crete syntax won't allow element type names longer than eight 
characters, it spits out a two-line error message for each one it 
finds in your DTD and document instance, and for an instance 
of more than a couple of lines, that's a lot of error messages. 

When the validation command pops up in your minibuffer, 
your cursor will be there, so move it to the appropriate place 
and enter the name of a file with the appropriate SGML decla- 
ration: 

Validate command: nsgmis -s . . \catalog\docbook.dcl whalin.sgm 
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PSGML assumes that the parsing program is in your path. If it 
can't find it, you'll see an error message in the output window. 

Validator Output 

When you press Enter to accept the validation command in 
your minibuffer, PSGML splits your screen to create a new win- 
dow with a buffer titled *sgmi validation*. The command 
executing the validator appears in that window and the valida- 
tion program goes to work, as shown in Fig. 2.43. 

If the word "done" eventually appears at the end of the 
minibuffer message and you never see anything else happen, 
then congratulations — ^the validator found nothing wrong with 
your document. 

If the validator does find errors, it lists them in the validation 
message window. PSGML makes it easy to sort through the 
messages and quickly find the problems that they identify in 
the document. Let's add two errors to an otherwise valid file 
and see what the error messages look like. 

The following shows the beginning of a document that con- 
forms to the DocBook DTD, with two exceptions: I put a stray 
secti start-tag between the emphasis tags around the word 
"shirt" and I gave the second para element a hair attribute it 
doesn't have, with an attribute value of "red." 
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m 

Buffets Files Tools Edit Seaich DSSSL SGML Modify Move Maii^up View DTD Help 
<?DOCTVPE chapter PUBLIC "-//Dauenport//DTD DocBook U2.4.1//EN"> 
<chapter> 

<title>Gone Whalin ■ </title> 

<sect1> 

<title>The Carpet-Bag</title> 

<para>I stuffed a <emphasi5>shlrt<sect1>B/enphasis> or two into my 
old carpet-bag, <eriphasis>tucked</eniphasis> it under ni; arn, and 
<emphasis>started</emphasis> for Cape Horn and the Pacific .</para> 

<para hair=red>Quitting the good city of old Manhatto, I duly 
arrige in New Bedford. </para> 

<para>It uas on a Saturday night in December .</para> 



Enacs: whalin.sqn 



cd c :/dat/sgnlf ree/ 
nsgnls -s uhalin.sgm 



(SGML [chapter] Compiling)— L6— Ml 



-Emacs: «sanl ualidation» 



tT:SGHL ualidation :run Compiling)- 



Figure 2.43. sgml-validate begins validating the document 



<!DOCTYPE chapter PUBLIC "-//Davenport//DTD DocBook V2.4.1//EN"> 
<chapter> 

<title>Gone Whalin' </title> 

<sectl> 

<title>The Carpet-Bag</title> 

<para>I stuffed a <emphasis>shirt<sectl></emphasis> or two into my 
old carpet-bag, <emphasis>tucked</emphasis> it under my arm, and 
<emphasis>started</emphasis> for Cape Horn and the Pacific. </para> 

<para hair=red>Quitting the good city of old Manhatto, I duly 
arrive in New Bedford. </para> 

<para>It was on a Saturday night in December . </para> 
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After pressing c-c C-v and sending this document instance 
to nsgmis, the following error messages appear in the valida- 
tion window: 



nsgmis : whalin. sgm: 6 : 43 :E : document type does not allow element "SECTl" here 
nsgmis :whalin. sgm: 5: 54 :E: "SECTl" not finished but containing element ended 
nsgmls:whalin.sgm:6:54:E: end tag for "SECTl" omitted, but OMITTAG NO was 

specified 

nsgmis : whalin. sgm: 5: 37 : start tag was here 

nsgmis :whalin. sgm: 9: 15 :E: there is no attribute "HAIR" 

nsgmls:whalin.sgm:ll:57:E: end tag for "SECTl" omitted, but OMITTAG NO was 
specified 

nsgmis : whalin. sgm: 4 : 1 : start tag was here 

nsgmls:whalin.sgm:ll:57:E: end tag for "CHAPTER" omitted, but OMITTAG NO was 
specified 

nsgmis : whalin. sgm: 2 : 0 : start tag was here 



These messages have a couple of things in common with 
programming-related error messages, both to our advantage: 

• The ripple effect of one error causing many error messages 
means that you shouldn't panic when you see a lot of error 
messages. We already know that the document instance 
only has two problems, so the next time you see eight 
error messages, maybe they're the result of only two prob- 
lems. 

• Emacs has a special command, automated by a keystroke, 
that quickly finds the text line that caused each error mes- 
sage. We can use this to locate SGML errors. 

The Emacs next-error keystroke (c-x ^ is not a special 
PSGML command, which is why it doesn't begin with c-c. 
Programmers use it to find the lines in their source code that 
caused each compiler error message. It jumps the cursor in 
your document instance window to the line with the next error 
and lines up the first error message at the top of the *sgmi 
validation* window (see Fig. 2.44). 
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The extraneous secti tag caused five error messages and 
the hair "attribute" caused one. Error message lines without a 
one-letter code after the second number provide background 
information on the previous error; for example, the line after 
the one about the missing secti end tag tells us that the secti 
start tag was on character 37 of line 6. 

The "Parsing and Validating SGML Documents with nsgmis" 
chapter describes nsgmis and sgmis messages in more detail. 



Buffets Tools Edit Search DSSSL SGML Mo(% Mov* Marl up View DTD Help 
<«DOCTVPE chapter PUBLIC ■ -//DauenportZ/DTD DocBook U2.ii.1//EK"> 
<chaptet"> 

<title>Gone Whalin ■ </title> 

<sect1> 

<title>The Carpet-Bag</title> 

<para>l stuffed a <einphasis>shii-t<sect[]></emphasis> or two into ny 
old carpet-bag, <emphasis>tucked</eriphasis> It under ny arm, and 
<emphasis>started</enphasis> for Cape Horn and the Pacific .</para> 

<para hair=red>Quitting the good city of old Manhatto, I duly 
arrive in New Bedford .</para> 

<para>It uas on a Saturday night in December .</para> 



nsgnls:uhalin. 
nsgnls :uhalin . 
nsgnls luhalin . 
fied 

nsgnls :uhalin . 
nsgnls :uhalin . 
nsgnls luhalin . 
if ied 

nsgnls luhalin . 
nsgnls luhalin . 
ecif ied 
nsgnls:uhalin. 



sgnieiUSiE: docunent type does not allou element "SECT1" here 
sgn:6:S<«:E: "SECT1" not finished but containing element ended 
sgn:6:S;it:E: end tag for "SECT1" omitted, but OMITTflG NO uas speciX | 



sgn:6:37: start tag was here 
sgm:9:15:E: there is no attribute "HfllR" 
sgm:11:57:E: end tag for "SECTI" omitted. 



but 0I1ITTAG NO was spec\ 



sgm:<t:1: start tag was here 

sgm:11:S7:E: end tag for "CHBPTER" omitted, but OMITTRG NO uas sp\ 
sgm:2:0: start tag was here 



SGML ualidation exited abnormally with code 1 at Hon Jan 27 15:15:35 



Enacs: »sqml validation* (T:SGML ualidation :exit [1]) — L3 — Bot B 



J 



Parsing error messages done 



Figure 2.44. First error of output 
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When multiple error messages refer to the same line, press 
c-x ' to skip to the first error message of the next document 
line that has an error, and the document window cursor jumps 
to that line. (I suppose f irst-error-message-of-next- 
source-iine-with-error, while more accurate, would be 
too wordy compared with next-error.) With our example, 
pressing this keystroke three more times puts the document 
window cursor at the ninth line and lines up the error message 
about that line at the top of the validation window (see 
Fig. 2.45). 



Bulfets Files Tools Edit Seacch DSSSL SGML Modify Move Mackup View DTD Help 
<«DOCTVPE chapter PUBLIC "-//Dauenport//DTD DocBook U2.i|.1//EN"> 
<chapter> 

<title>Gone Whalin ■ </title> 

<sect1> 

<title>The Carpet-Bag</title> 

<para>I stuffed a <eraphasis>shit-t<sect1></enphasis> or two into ny 
old carpet-bag, <eriphasis>tucked</enphasis> it under arn, and 
<emphasis>started</einphasis> for Cape Horn and the Pacific .</para> 

<pard hair5red>Quitting the good city of old Manhatto, I duly 
arrige in New Bedford. </para> 

<para>It was on a Saturday night in December .</para> 



Enacs: whalin.sgn 



(SGML [chapter])— L9— nil 



nsgnls :whalin .sgn:9 :15 :E : there is no attribute "HftIR" ^ 
nsgnils:whalin.sgn:11 :57:E: end tag for "SECT1" omitted, but OMITTRG NO was spec\ 
if ied 

nsgnls :whalin .sgm:ii:1 : start tag was here 

nsgnls:whalin.sgn:11 :57:E: end tag for "CHftPTER" omitted, but OMITTAG NO was sp\ 
ecif ied 

nsgmls iwhalin .sgm:2 : B: start tag was here 

SGML validation exited abnormally with code 1 at Men Jan 27 15:'t9:'t5 



Enacs: "sgnl ualidation» 



(T:SGML validation :exit [1]) — L7— Bot 



Figure 2.45. Second error of output 
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If you press C-x ' when there are no more errors, a 
minibuffer error message tells you "No more errors." 

Changing the Validation Command 

PSGML creates a variable in the Emacs environment called 
sgmi-vaii date-command to Store the command it executes 
when you press c-c c-v. If you want to change this command, 
you can set it to a different value in your . emacs file. For exam- 
ple, let's say the Emacs describe-variabie keystroke (c-h 
v) shows that the sgmi-vaiidate-command variable has the 
following value: 

nsgmls -s %s %s 

(The %s %s shows where Emacs substitutes the name of the 
file being edited when it is executed. The syntax will be famil- 
iar to C programmers.) If you want PSGML to use the sgmls 
program instead, the following line in your .emacs file sets the 
variable to run sgmls when you enter c-c C-v: 

(setq sgml-validate-command "sgmls -s %s %s") 

Remember how the validation command might need an 
SGML declaration file? If you often use the same SGML decla- 
ration file, you can add it to the . emacs line that sets the sgml- 
validate-command variable so that you don't have to specify 
it every time you validate a file: 

(setq sgml-validate-command "sgmls -s WsgmlWdtdsWdocbook.dcl %s %s") 

(Note the use of double backslashes to put literal backslashes 
in the string.) Even if you add an SGML declaration file name to 
the default command, you don't have to use that declaration 
every time. After you press c-c c-v, you still have a chance to 
edit the validation command before PSGML executes it. 
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PSGML has too many features and too many ways to take 
advantage of them for this chapter to cover them all. Still, sev- 
eral more valuable tricks are worth mentioning. 

Displaying l\/larl(up in Different Fonts and Colors 

When you use a terminal (or terminal emulation program) 
and a version of Emacs that can show text in different fonts or 
colors, PSGML can take advantage of this to make it easier to 
distinguish between data content and different kinds of 
markup. Its default settings display SGML comments in italics; 
entity references in bold italics; and tags, processing instruc- 
tions, the SGML and DOCTYPE declarations, and short refer- 
ences in bold text. 

if your version of Emacs can show different fonts, you're 
probably using a UNIX version with an XWindows terminal. 
Other versions typically substitute colors for these fonts; for 
example, The EMX version of GNU Emacs 1 9.29.2 shows com- 
ments in red, entity references in yellow, and tags and other 
markup in white text against its default gray background. 

If you've issued the sgmi-next-troubie-spot command 
and you still don't see any fonts or colors, you can tell Emacs 
and PSGML to display markup in your choice of colors by add- 
ing a few lines to your .emacs file. These lines must perform 
four basic steps: 

1 . Create "faces" to assign to the markup categories. 

2. Assign attributes to the faces. 

3. Assign faces to markup categories. 

4. Set the sgmi-set-f ace variable to a non-nil value so that 
PSGML knows to pay attention to the face settings. 

The following .emacs code demonstrates how to assign col- 
ors to comments, tags, and entity references. 



89 



SGML CD 



;;;;; Assign colors to markup. ;;;;; 

; Create faces to assign to markup categories, 
(make-face ' sgml-comment-f ace) 
(make-face ' sgml-start-tag-f ace) 

(make-face ' sgml-end-tag-face) 
(make-face ' sgml -entity-face) 

; Assign attributes to faces. Background of white 
(set-face-foreground ' sgml-comment-f ace "White") 
(set-face-background ' sgml-comment-f ace "Gray") 
(set-face-background ' sgml-start-tag-f ace "Gray") 
(set-face-background 'sgml-end-tag-face "Gray") 
(set-face-foreground ' sgml-entity-face "White") 
(set-face-background 'sgml-entity-face "Black") 

; Assign faces to markup categories, 
(setq sgml -markup-faces 

' ( (comment . sgml-comment-f ace) 

(start -tag . sgml-start-tag-f ace) 

(end-tag . sgml-end-tag-face) 

(entity . sgml-entity-face) ) ) 

; Tell PSGML to pay attention to face settings, 
(setq sgml-set-face t) 

A couple of things to note: 

• To list the available colors, enter the Emacs command 
list-colors-display at the M-x command prompt. The 
choice varies depending on your version of Emacs. 

• My choices don't seem very colorful because I picked set- 
tings that make this chapter's illustrations easier to repro- 
duce on the printed page. 

• The above example sets the start- and end-tags to the same 
color, but this is not required. 

• You can set both foreground and background colors if you 
wish. I left the tag and comment backgrounds and the 
entity foreground color (that is, the actual text color) at the 
default settings. 



assumed. 

; Comments: white on 

; gray. 

; Tags: black (default) 

; on gray. 

; Entity references: 

; white on black. 
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I only set the comment, start-tag, end-tag, and entity 
appearances in the setq sgmi -markup-faces part, but you 
can also set the colors of doctype declarations, ignored 
marked sections, ms-start for the start and ms-end for end of 
non-ignored marked sections, pi for processing instructions, 
sgmi for the SGML declaration, and shortref for short refer- 
ences. Just remember to create faces for them and set the faces' 
attributes before the final step. 

Normalizing Document Instances 

The sgmi-normaiize command expands any empty tags 
and fills in omitted tags in a document instance. In other 
words, it makes sure that every non-empty element has a 
beginning and end-tag, whether or not the DTD requires it. 

Much SGML software requires normalized SGML, so this 
command is a quick way to prepare your instance for use with 
such programs. This command is not assigned to a keystroke 
because you rarely need it more than once or twice in an edit- 
ing session, so run it by selecting Normalize from the Modify 
menu or by entering sgmi-normaiize at the minibuffer m-x 
prompt. 

Help Entering Entity References and Markup Declarations 

The sgmi-compiete keystroke (M-Tab) tries to help you 
complete the entity reference, markup declaration, tag, or even 
data content word that you are entering when you press it. 
We've already seen how PSGML can help you enter element 
type names; M-Tab can only help you enter content text words 
if you have the ispeii program available (an Emacs spell- 
checking utility — DOSAA/indows Emacs users should see 
http : //cat . rpi . edu/~tibbetts/ispell_port . html for a 

special version) but the entity reference and markup comple- 
tion capabilities can be valuable. 
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PSGML knows that you're entering an entity reference when 
you've entered an ampersand and haven't entered a space fol- 
lowing it yet. If you press M-Tab right after entering the amper- 
sand, it lists all the valid entities whose name you might be 
entering in a separate window. If you follow the ampersand 
with enough letters to let PSGML narrow its guess down to 
one, it fills in that entity reference for you. For example, in 
Fig. 2.46, let's say you only typed the "&md" just before the 
emphasis Start tag. 



<para>It was on a Saturda}) night in December .</para> 
<para>Unconsciously clapping the uinegar-cruet to one side of 
her nose, she ruminated for an instant; then 

pxclai npd f3WB <pnnhasi s>Nn?</pranhasis> I hauen't seen it since I put it 
there. '</para> 



Figure 2.46. Entering the beginning of an entity reference 

If you then press M-Tab and mdash is the only declared 
entity beginning with the letters "md," PSGML enters the "ash" 
for you, as shown in Fig. 2.47. 



<para>It uas on a Saturday night in December .</para> 
<para>Unconsciously clapping the uinegar-cruet to one side of 
her nose, she ru minated for an instant; then 

exclaimed fBnT!TjH1B <emDhasis>No«</emnhasls> I hauen't seen it since I put it 
there . ' </para> 



Figure 2.47. Completing the entity reference with M-Tab 

Note that you must still enter the semicolon to complete the 
entity reference. 

The sgmi-compiete command completes a markup decla- 
ration, which you're more likely to use in a DTD than in a doc- 
ument instance. For example, entering "<!" with no letters to 
give a clue about which declaration you want and then press- 
ing M-Tab opens up a new window and displays the following 
list of possible completions: 
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sgml 



doctype 
entity 
shortref 
attlist 

linktype 
idlink 



element 

usemap 

notation 

uselink 

link 



Showing the Live Element's Context 



In the section "PSGML Startup Variables," we saw that set- 
ting the Emacs variable sgml-live-element-indicator tO a 
non-nil value tells PSGML to display the document type and 
the current live element on the mode line. To learn more about 
the role of the live element in the document's structure, the 
sgmi-show-context keystroke (c-c c-c) lists the live ele- 
ment's ancestry from itself to the doctype, showing the live ele- 
ment's parent, that element's parent, and so forth all the way 
up to the top (that is, to the document element). 



<sectl> 

<title>Biographical</title> 

<para>Queequeg was a native of <emphasis>Kokovoko</emphasis>, an 
island far away to the West and South. </para> 



For example, with your cursor on the word "Kokovoko" in 
the text above, pressing C-c C-c displays the following in the 
minibuffer: 



Selecting Show Context from the SGML menu also does this. 



Quick Reference of Emacs and PSGML Keystrokes 



Keep the following list handy as you get used to Emacs and 
PSGML keystrokes. You'll find a copy of it in the file psgm- 
qref . txt on the enclosed CD-ROM. 



tPCDATA in emphasis in para in sectl in chapter 
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Table 2-1. Moving Your Cursor Around: Regular Emacs Keystrokes 



C— f forward-char 

C— b backward-char 

C— Left backward-word 

C— Right forward-word 

C-a beginning-of -line 

C— e end-of-line 

C-v scroll-up 

M— V previous-page 

M— b backward-word 

M— f forward-word 

M-g goto-line 



Or, "cursor right." 
Or, "cursor left." 



Or, "page down." 
Or, "page up." 



Not a regular Emacs command, but 
set by a line in the . emacs file 
described in this chapter. 



Table 2-2. Moving Your Cursor Around: PSGML Keystrokes 



C— M— a sgml-beginning- 
of-element 

C— M— e sgml-end-of- 
element 

C-c C-d sgml-next-data- 
field 

C— c C— n sgml-up-element 



C— M— u sgml-backward-up- 
element 



First data character of current ele- 
ment. 

Last data character of current ele- 
ment. 

Next place where you can enter 
data. 

Up in element hierarchy to next 
character in current element's par- 
ent element. 

Up in element hierarchy to begin- 
ning of current element's start-tag. 
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sgml-down-element Beginning of current element's next 

subelement. 



sgml-backward- 
element 

sgml- forward- 
element 



Beginning of current element's pre- 
vious subelement. 

Right after current element's next 
component element. 



Table 2-3. Adding, Deleting, and Moving Text: Regular Emacs Commands 



delete-char 

s e t -ma r k - c omma n d 

set -mark-command 
kill-region 

kill-line 

exchange -point - 
and-mark 

yank 

kill-word 
overwrite-mode 

fill-paragraph 
kill-ring- save 

yank-pop 



Cut marked region into "clipboard" 
(kill ring buffer). 

From cursor to end of line. 

Jump cursor to marked region's 
other boundary. 

"Paste" from kill ring buffer to cur- 
sor position. 



A toggle. Not a regular Emacs com- 
mand, but set by line in . emacs 
file. 

Justify paragraph. 

Copy to "clipboard" (kill ring 
buffer). 

Replace recently yanked text with 
previously killed or copied text. 
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indent -region 



Indent region's lines. In PSGML 
mode, it indents tags to show ele- 
ment structure. 



quoted-insert Insert next entered character liter- 

ally, even if it's normally part of a 
command keystroke. 

Table 2-4. Adding and Removing SGML Markup and Elements 



e sgml-insert- 
element 

sgml-insert-tag 



sgml-insert-end- 
tag 

r sgml-tag-region 



sgml-untag- 
element 



k sgml-kill-markup 



sgml-split- 
element 



sgml- comment 



sgml -kill -element 



Insert a start-tag. Best when adding 
tags to existing text, as opposed to 
adding a new element whose con- 
tent you haven't typed yet. 

Insert an end-tag. As with C-c <, 
most valuable when adding tags to 
existing text. 

Add start- and end-tags around 
marked region. 

Remove live element's start- and 
end-tags. Most useful with in-line 
tags. 

Kill a tag, comment, or other piece 
of markup. 

Or, "make a new element like the 
current one." Repeat to split higher- 
level elements. 

A macro added to . emacs file as 
part of the chapter. 

Kill text from cursor to end of next 
subelement. 
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C-space Delete remainder of current ele- 

C-M-e ment. 

C-w 

M-Tab sgml-complete Complete the entity reference, 

markup declaration, tag, or con- 
tent word at the cursor. 

C-M-u Copy current element to kill ring. 

C-@ 

C-M-f 

M-w 

C-c C-q sgml-f ill-element Justify current element. 

C-c + sgml-insert- Edit current element's attribute val- 

attribute ues using prompts. 

C-c C-a sgml-edit- Edit current element's attribute val- 

attributes ues using a form in a separate 

Emacs window. 

Table 2-5. Getting Help and Other Information 

C-h Display help menu. 

C-h ? help-f or-help Describe use of on-line help. 

C-h a command-apropos List commands with a certain string 

in them. 

C-h k describe key Describe the next key pressed after 

C-h k. 

C-c C-c sgml-show-context Or, after a C-c C-a, end attribute 

editing. 

C-x ' next-error Find next error in error message 

window. 
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C-c C-o sgml-next- Move cursor to next potential 

trouble-spot markup problem. 

C-c C-v sgml-validate Send document instance to valida- 

tion program. 

Table 2-6. Controlling Files, Buffers, and Windows 

C-x 0 delete-window Delete cursor's current window. 

C-x 1 delete-other- Make the cursor's window the only 

windows one. 

C-x 2 split-window- Split into a top and bottom win- 

vertically dow. 

C-x o other-window Repeated pressing cycles cursor 

through open windows and 
minibuffer. 

C-x b switch-to-buffer Display a different buffer in cursor's 

current window. 

C-x C-b list-buffers List open buffers in a new window. 

C-x C-s save-buffer As a disk file. 

C-x C-w write-file As a disk file, under a new name if 

you like. 

C-x C-c save-buf f ers- Answer prompts about saving each 

kill-emacs current buffer, then quit Emacs. 

C-x C-f find-file Open a new or existing file. 

C-x i insert-file Insert an existing disk file at the 

current cursor position. 
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Table 2-7. Emergencies 

C-g keyboard-quit Abort current multi-step operation. 

C-_ undo Undo last command. 

Table 2-8. Customized Beliavior 

C-x ( start-kbd-macro Start recording a macro. 
C-x ) end-kbd-macro Stop recording a macro. 

C-x e call-last-kbd- Execute last recorded macro. 

macro 

C-u set-fill-column Set right margin to the (number) 

(number) column. 
C-x f 

M-x execute-extended- Display Emacs command prompt in 

command minibuffer. 

Table 2-9. Searching and Replacing 

C-s isearch-f orward Incremental search forward. 

C— r isearch-backward 

M-% query-replace Prompts for target and replacement 

text. 
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